Next-release readiness: repository hygiene, documentation audit, and publish handoff

[momics]

This was generated by AI during triage.

Why

v0.6.0 is already published. Before the next release, do one deliberate repository-readiness pass so temporary review artifacts, stale public documentation, and release-process drift do not ship again.

This is an umbrella chore. The final step is intentionally a human publishing gate.

Workstreams

1. Repository hygiene

• Remove the tracked, PR-specific PR_350_REMEDIATION_AUDIT.md; it contains stale pre-merge state and a machine-local worktree path.
• Scan all tracked files for temporary reviews, generated reports, patches, logs, build products, device artifacts, machine-specific paths, and orphaned documents. Record a keep/remove decision for every candidate in the PR description.
• Resolve the orphaned docs/internals/core-performance-exploration-2026-06.md: retain the useful benchmark history only if it is linked from the internals index and all machine-specific Cargo paths are made portable; otherwise remove it.
• Preserve purposeful tracked assets such as ADRs, DNS-SD verification contracts, native contract harnesses, and output-directory placeholders.
• Do not publish ignored or untracked local-only workspace material. Public audit notes should describe excluded candidates by category, without exposing private filenames, tool inventories, usernames, or machine paths.
• chore: consolidate project agent skills #381 established .agents/skills/** as the single cross-agent project-skill location, retained the blanket .agents ignore as a privacy boundary, and explicitly tracked only the reviewed repository skills: manage-issues, fix-issues, regression-first, and analyze-git-diff.
• Keep standing repository rules in AGENTS.md; do not duplicate skills across agent-specific directories or vendor general-purpose skill collections that are better installed and updated at user/plugin scope.
• Require deterministic skill tooling to carry regression fixtures and run those fixtures in CI. The diff analyzer must continue matching Git's exact totals before publishing its heuristic classifications.

2. Documentation and README audit

Audit every tracked README.md, plus any directly linked setup guide whose instructions it depends on. At minimum:

• Replace stale package versions and commands; public installation snippets must match the next release version or use the repository's documented versioning convention.
• Update the root support statement so Tauri mobile is not described as unsupported.
• Correct the discovery configuration example to the actual mdns?: boolean | { serviceName?: string } shape.
• Make the Tauri package README accurately list desktop, iOS, and Android support and point clearly to mobile setup.
• Replace the stock Tauri example README with instructions for this repository's actual example: prerequisites, desktop/mobile build and run commands, signing expectations, capabilities, discovery testing, and troubleshooting.
• Make iOS DNS-SD setup explicit: native framework linkage, local-network usage text, Bonjour service declarations, and the Tauri discovery capability.
• Make Android DNS-SD setup explicit: plugin-owned manifest entries, pre-T-extension-7 multicast-lock behavior, T-extension-7 foreground behavior, the future API-37 local-network runtime permission, the Tauri discovery capability, and lifecycle constraints.
• Rewrite stale mobile discovery claims that still describe the pre-feat: cross-device interop — land #338/#336/#346 + #340 harness (device-validated, consolidated) #350 asymmetric matrix or the old iOS advertiser implementation.
• Verify Deno FFI flags against the currently supported Deno version and remove duplicate/outdated wording.
• Reconcile compression documentation with the current Cargo feature model and runtime behavior.
• Repair stale public API documentation: the core Rust sample must use the current service/fetch interfaces, the adapter README must describe its validation and request-delivery responsibilities and current error mapping, and the shared-package README must name dial()/incoming() plus the peer and generic discovery APIs.
• Update release instructions to the guarded flow actually used: the release script's clean-main/git-cliff prerequisites, tag-triggered draft Build plus Extended checks, manual Publish dispatch only after the exact tag is green, registry verification, then publishing the GitHub draft.
• Refresh test-suite counts/file listings and complete the feature/internals indexes, or replace brittle hand-maintained counts with a generated check.
• Audit directly linked API/setup pages for obsolete option names such as flat relay, DNS resolver, timeout, or advanced configuration fields.
• Check all README links and run/compile documentation examples where practical.

Android support needs a code-versus-documentation decision, not a permission list copied blindly:

• Verify multicast reception on the supported pre-T-extension Android range. If a WifiManager.MulticastLock is required there, implement and lifecycle-test it or document a deliberately narrower support floor.
• Verify what the plugin contributes to the merged manifest versus what a generated Tauri app must own, including runtime permission handling where applicable.
• Track Android's newer local-network permission model explicitly rather than claiming untested future SDK support.

3. Release candidate gate

• Land the cleanup/documentation PR with normal CI green and a clean tracked tree.
• Confirm the chosen next version, package manifests/lockfiles, and curated changelog agree.
• Resolve or incorporate Release workflow should publish the curated CHANGELOG section #379 so the release workflow uses the curated changelog section instead of replacing it with raw generated notes.
• Re-run the relevant desktop and mobile DNS-SD verification matrix if implementation or setup instructions changed materially.
• If Android multicast/runtime behavior changes, run the affected real-device matrix rather than treating it as documentation-only work.
• Obtain explicit maintainer approval before creating the next release tag.
• Tag the exact approved main-branch commit and watch the tag-specific Build, Extended, and Benchmarks workflows to green. Record workflow links and the exact commit SHA here.

4. Human publish — final step

• Hand the maintainer a concise publish checklist with the tag, commit, green workflow links, expected package/artifact inventory, and curated release notes.
• Human: manually dispatch/approve publishing, verify registry/package availability, publish the GitHub release, and close this issue.

Scope boundaries

• Do not move or recreate the already-published v0.6.0 tag.
• Do not mix product/API changes into the cleanup PR unless a documentation claim exposes a real release blocker; track such work separately.
• Preserve developer worktrees and unrelated local state. Perform implementation in a fresh branch/worktree from current main.
• Do not publish automatically. The final publish decision remains human-owned.

Completion evidence

• Cleanup PR link and its tracked-file audit summary
• List of all README files checked, with changed/unchanged rationale
• Documentation/example validation commands and results
• Exact release tag and commit SHA
• Green tag-workflow links and artifact inventory
• Human confirmation that packages and GitHub release are public

[momics]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Prepare the repository and documentation for the next release, validate the tagged release candidate, then hand publishing to a human.

Current behavior:
The repository still contains a stale PR-specific remediation audit and an orphaned performance exploration with machine-local commands. Public documentation contains stale package versions, incomplete Tauri mobile setup, invalid or outdated configuration examples, and pre-fix DNS-SD behavior claims. The last release also demonstrated that generated release notes can replace the curated changelog. Local-only review reports and agent skills exist in one dirty checkout but are not tracked on main.

Desired behavior:
Tracked files should contain only durable project assets. Every public README and its directly linked setup instructions should accurately describe the supported runtimes and current APIs, including complete iOS and Android DNS-SD configuration. The reusable diff-analysis skill should follow the repository's established skill convention rather than relying on local agent state. Once normal CI and release metadata are consistent, an explicitly approved tag should be validated through all tag workflows. Publishing must remain a final human action with a complete handoff.

Key interfaces:

• Public package installation and runtime-support documentation — versions, platforms, commands, and links must match the release candidate.
• NodeOptions.discovery.mdns — examples must accept either a boolean or an object containing the optional service name.
• Tauri mobile integration contract — iOS local-network/Bonjour declarations, Android network/multicast/nearby-Wi-Fi permissions, and the discovery capability must be documented and verifiable.
• Android multicast lifecycle — documentation and implementation must agree on whether older supported devices require an acquired multicast lock, which manifest entries are plugin-owned versus app-owned, and which runtime permissions apply.
• Repository skill convention — reusable skills belong in the tracked GitHub skills location and must not depend on ignored local agent files.
• Release workflow — curated changelog content, tag SHA, required workflows, artifacts, and the human publish boundary must be explicit.

Acceptance criteria:

• A tracked-file audit identifies all temporary/generated/machine-specific candidates and records a justified keep, sanitize, migrate, or remove decision.
• The stale PR remediation artifact is absent from the release candidate.
• No local review report, ignored agent state, editor state, device build, or generated report is introduced.
• The reusable git-diff analysis skill is validated in the repository's tracked skill convention and has discoverable usage documentation.
• Every tracked README is reviewed; the pull request records which were changed and why unchanged files remain accurate.
• Installation versions, supported-platform claims, API examples, Deno commands, compression claims, and links match the release candidate.
• Core Rust, adapter, shared-package, test-suite, and release-process READMEs reflect their current callable interfaces, responsibilities, inventory, and workflow gates.
• A developer can configure DNS-SD discovery in a Tauri iOS or Android app using only the documented prerequisites, permissions, capabilities, build/run steps, and troubleshooting guidance.
• Android DNS-SD behavior is validated across the documented supported SDK range; any multicast-lock or runtime-permission requirement is implemented and lifecycle-tested or the support claim is narrowed explicitly.
• Stale descriptions of the old asymmetric DNS-SD matrix and old native implementation are removed.
• Documentation examples and links are validated with recorded commands/results where automation is practical.
• Directly linked documentation contains no obsolete public option names, and a repeatable check catches broken local links and selected stale API/version literals.
• Normal branch CI is green, release version metadata and curated changelog agree, and the release-notes behavior tracked in Release workflow should publish the curated CHANGELOG section #379 is resolved or incorporated.
• No tag is created without explicit maintainer approval.
• The approved tag points to the recorded main-branch SHA and all required tag workflows are green with the expected artifacts.
• The agent stops before publishing and provides the human with all links, checksums/inventory where available, and release notes needed to publish safely.
• A human confirms registry/package availability and publishes the GitHub release as the final step.

Out of scope:

• Rewriting, moving, or republishing v0.6.0
• Unrelated product, protocol, or public API changes
• Deleting or overwriting the maintainer's dirty local checkout
• Automatically publishing packages or the GitHub release

[momics]

This was generated by AI during triage.

Implementation is ready for human review in #382.

The PR covers repository hygiene, the full README and directly linked documentation audit, legacy Android DNS-SD multicast ownership, and the curated changelog release-body fix from #379. Its description records every keep/remove decision, all 18 README outcomes, validation evidence, and the diff shape.

Independent review found and then verified fixes for legacy advertise-only Android, unnecessary locks on newer Android, runtime-default drift, stale release guidance, lifecycle test gaps, and duplicate changelog sections. No actionable findings remain.

Release state was also verified: v0.6.0 is already public on GitHub, npm, JSR, and crates.io. It must not be recreated or moved; after this PR lands and device verification is complete, the next candidate should use a new version, normally v0.6.1. No tag or publication action has been taken.

[momics]

This was generated by AI during triage.

Implementation landed

PR #382 merged into main at commit 1f85f4ad5efcd141cbb0bc6e0fb15c18d2742c0b:
#382

It also closed #379. All eight replacement checks passed:

• CI: https://github.com/momics/iroh-http/actions/runs/29722658914
• Coverage: https://github.com/momics/iroh-http/actions/runs/29722658907

A three-part independent audit covered repository/privacy boundaries, mobile setup and DNS-SD behavior, and release-process accuracy. The audit found nine documentation/process gaps; all were addressed before merge. The final clean-checkout validation successfully installed locked dependencies, built the local shared/Tauri packages and example frontend, and compiled the desktop Tauri application in release mode without bundling.

The reusable physical-device runbook now records the exact candidate SHA, iOS version, Android API and T-extension level, directed suite results, generic DNS-SD behavior, Android browse/advertise lifecycle, and whether the legacy multicast-lock branch was physically exercised. Public results must remain sanitized.

Remaining release gates

1. Run the physical desktop/iOS/Android matrix against exact main commit 1f85f4a.
2. Record legacy Android as pass/fail, or explicitly accept residual risk if no API 21–32 / pre-T-extension-7 device is available.
3. Confirm the next version (normally v0.6.1) and run the guarded release preparation so manifests, lockfiles, and the curated changelog agree.
4. Obtain explicit maintainer approval before creating the tag.
5. Watch Build, Extended tests, and Benchmarks for the exact tag to green.
6. Human-dispatch Publish, verify registries/assets, publish the GitHub draft, and close this issue.

No release tag or publication action has been taken.

[momics]

This was generated by AI during triage.

Repository-ref hygiene completed

• Pruned 32 obsolete remote branches: 27 were already merged into main; five had no open PR and were closed, superseded, or abandoned.
• Preserved all nine active Dependabot PRs and updated each branch onto current main.
• Verified the updated active PR branch trees contain the sanitized portable benchmark documentation.
• Confirmed the temporary backup tag was already absent from GitHub and removed its stale local copy.
• Re-cloned a fresh remote mirror and verified that no current branch tip contains the machine-specific path material addressed by the cleanup.
• Left the already-published v0.6.0 tag unchanged, per this issue's scope boundary.

The remaining work is still the release gate: exact-main physical verification, v0.6.1 metadata/changelog preparation, explicit tag approval, green tag workflows, and human publication.

[momics]

This was generated by AI during triage.

Exact-main modern Android evidence

Tested the APK built from 1f85f4ad5efcd141cbb0bc6e0fb15c18d2742c0b on Android 16 / API 36.

• Installation and app startup succeeded with no Android runtime or DNS-SD startup errors.
• Generic DNS-SD browsing discovered the desktop demo-printer advertisement.
• Android-to-desktop interop completed all 107 cases: 106 pass, 0 fail, 1 expected relay-fallback skip.
• Direct-dial transport was measured as direct.
• Request-body cases at 4 KiB, 64 KiB, 1 MiB, and 5 MiB all returned HTTP 200 and passed.
• The Test view temporarily appeared to show stale body-size failures despite the successful authoritative report; tracked separately in Test view can show stale failures after an interop suite completes successfully #386.

This verifies the modern Android no-multicast-lock branch. The legacy pre-T-extension-7 multicast-lock branch still requires an older device or explicit residual-risk acceptance.

[momics]

This was generated by AI during triage.

Modern Android DNS-SD lifecycle complete

The exact-main Android 16 / API 36 device completed the remaining generic DNS-SD lifecycle checks:

• Android browse discovered the desktop advertisement.
• Browse stop/restart rediscovered the advertisement.
• Desktop browse discovered the Android advertisement.
• Stopping Android advertising produced removal behavior.
• Restarting Android advertising produced a fresh active record.

Together with the submitted Android-to-desktop interop report (106 pass, 0 fail, 1 expected skip), the modern Android no-multicast-lock path is verified. The only Android-specific residual-risk decision is whether to require a physical pre-T-extension-7 device for the legacy multicast-lock branch or accept the contract-test coverage for this release.

[momics]

This was generated by AI during triage.

Release-safety blocker resolved

PR #390 merged at 0d2cf024de0c2d1e0c6fc9e2ad0e5f70f011960f after all eight PR checks passed: #390

The release bump no longer regenerates the third-party dependency graph after pre-release CI. A real disposable 0.6.1 bump now changes 52 project-version lines and zero third-party dependency versions; the previous behavior produced roughly 2,800 lines of lockfile churn. Regression coverage proves unrelated npm lock entries are preserved.

The exact-main v0.6.1 changelog preview is coherent and limited to the landed maintenance work: Android legacy multicast lifecycle, curated release notes, the Android-only QUIC GSO compatibility policy, repository/documentation cleanup, project-skill consolidation, and release lockfile stability. No tag or publish action has been taken.

Physical evidence carried into the candidate

PR #389 records three consecutive physical Android-to-desktop runs at 107 pass / 0 fail / 0 skip, including the 4 KiB, 64 KiB, 1 MiB, and 5 MiB body cases, plus the generic DNS-SD smoke test. The earlier exact-main Android evidence records browse/advertise stop-restart lifecycle behavior. Non-Android platforms retain the upstream GSO default.

Remaining maintainer gates

1. Explicitly accept the residual risk for the legacy pre-T-extension-7 Android multicast-lock branch, which has contract-test coverage but no available old physical device, or provide such a device for testing.
2. Explicitly approve v0.6.1 as the next release and authorize creation of its release commit/tag from the then-current exact main tip.
3. Watch tag-specific Build, Extended, and Benchmarks workflows to green.
4. Human-dispatch Publish, verify packages/assets, publish the GitHub draft, and close this issue.

The only other open issues are intentional upstream-removal trackers #368 and #388; neither should block this patch release.

[momics]

This was generated by AI during triage.

Post-merge main validation for release-safety commit 0d2cf024de0c2d1e0c6fc9e2ad0e5f70f011960f is green:

• CI (Verify, end-to-end, benchmark smoke): https://github.com/momics/iroh-http/actions/runs/29751700318
• Coverage: https://github.com/momics/iroh-http/actions/runs/29751700422

The implementation phase is complete. The release remains intentionally paused at the explicit maintainer approval gate described above.