fix(docs): Update DOCS.md with Thread creds sync instructions

[tyeth]

Hey, I wasted a lot of time on setup today, because everything was fine except the credentials sync in the android companion app [hidden in troubleshooting].
That piece of information is available on the thread integration's docs page, but not the open thread border router, which is where the matter signup process fails [android says you need a thread border router - which you have already setup via HA].
Adding to the docs page of the OTBR app is the first place people will look.
It might make more sense to have the how-to-use section containing the OTBR/mobile guidance, at least until the home assistant companion app can do the sync automatically as you add your network/HA-instance in the mobile app.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guidance for synchronizing Thread network credentials across Android and iOS mobile devices. New documentation provides detailed step-by-step in-app navigation instructions specific to both platforms, helping users successfully configure Thread integration and transfer network credentials to their Android smartphones and iPhones.

[home-assistant]

Hi @tyeth

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

Stale

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation update adding instructional guidance for syncing Thread credentials on Android and iOS devices, including platform-specific navigation paths and steps within the OpenThread Border Router documentation.

Changes

Cohort / File(s)	Summary
Documentation openthread_border_router/DOCS.md	Added multi-paragraph guidance section explaining how to sync Thread credentials for Android and iOS users, including step-by-step navigation instructions for each platform.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(docs): Update DOCS.md with Thread creds sync instructions' accurately describes the main change: adding Thread credential synchronization instructions to the documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into master

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.

In `@openthread_border_router/DOCS.md`:
- Around line 55-60: Reword the two steps to be goal‑first by leading with the
action (e.g., "Send/sync Thread credentials to your phone") then follow with
concise platform-specific steps; for Android, start with the goal then "On the
HA app go to Settings > Companion App > Troubleshooting > Sync Thread
credentials"; for iPhone, start with the goal then "In the HA app go to Settings
> Devices & services, select the Thread integration, Configure under Services,
and tap 'Send credentials to phone' at the bottom of the preferred network box";
ensure the exact phrases "Sync Thread credentials" and "Send credentials to
phone" remain intact for discoverability.
- Around line 49-53: Rewrite the paragraph to be a direct, imperative
instruction that fronts the goal (adding devices via mobile) while keeping UI
strings bold; specifically change the indirect sentences around the **Use router
for Android and iOS credentials** option and the Home-Assistant companion app
into commands (e.g., "Select your preferred network in Thread settings, enable
**Use router for Android and iOS credentials**, then add devices from the
Home-Assistant companion app and sync the Thread credentials."), and preserve
the bold UI text and the reminder to sync credentials.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Make the instruction direct and goal‑fronted.
Current phrasing is indirect (“You will still need…”, “you can…”). Use a direct instruction and front the goal; keep UI strings bold.

✅ Proposed rewrite

-You will still need to go to the Thread settings page and select your preferred
-network, choose the option for **Use router for Android and iOS credentials**, 
-and then you can add devices using your mobile via the Home-Assistant companion
-app. **Don't forget to sync the credentials** for the Thread network with your
-companion app.
+Select the Thread network and enable **Use router for Android and iOS credentials**.
+Add devices in the Home Assistant Companion app after you sync Thread credentials.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	You will still need to go to the Thread settings page and select your preferred
	network, choose the option for **Use router for Android and iOS credentials**,
	and then you can add devices using your mobile via the Home-Assistant companion
	app. **Don't forget to sync the credentials** for the Thread network with your
	companion app.
	Select the Thread network and enable **Use router for Android and iOS credentials**.
	Add devices in the Home Assistant Companion app after you sync Thread credentials.

🤖 Prompt for AI Agents

Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.
In `@openthread_border_router/DOCS.md` around lines 49 - 53, Rewrite the paragraph
to be a direct, imperative instruction that fronts the goal (adding devices via
mobile) while keeping UI strings bold; specifically change the indirect
sentences around the **Use router for Android and iOS credentials** option and
the Home-Assistant companion app into commands (e.g., "Select your preferred
network in Thread settings, enable **Use router for Android and iOS
credentials**, then add devices from the Home-Assistant companion app and sync
the Thread credentials."), and preserve the bold UI text and the reminder to
sync credentials.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Front the goal in the step instructions.
These steps start with location (“On an Android phone…”) instead of the goal. Rephrase to goal‑fronted instructions.

✅ Proposed rewrite

-On an Android phone in the HA app go to **Settings** > **Companion App** >
-**Troubleshooting** > **Sync Thread credentials**.
+Sync Thread credentials on Android: In the Home Assistant app, go to
+**Settings** > **Companion App** > **Troubleshooting** > **Sync Thread credentials**.
 
-Or for an iPhone, go to **Settings** > **Devices & services**, select the
-Thread integration, select **Configure** under Services. At the bottom of the
-preferred network box, select **Send credentials to phone**.
+Send Thread credentials to iPhone: In the Home Assistant app, go to **Settings**
+> **Devices & services** > **Thread** > **Configure**, then select **Send credentials to phone**.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	On an Android phone in the HA app go to **Settings** > **Companion App** >
	**Troubleshooting** > **Sync Thread credentials**.
	Or for an iPhone, go to **Settings** > **Devices & services**, select the
	Thread integration, select **Configure** under Services. At the bottom of the
	preferred network box, select **Send credentials to phone**.
	Sync Thread credentials on Android: In the Home Assistant app, go to
	**Settings** > **Companion App** > **Troubleshooting** > **Sync Thread credentials**.
	Send Thread credentials to iPhone: In the Home Assistant app, go to **Settings**
	> **Devices & services** > **Thread** > **Configure**, then select **Send credentials to phone**.

🤖 Prompt for AI Agents

Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.
In `@openthread_border_router/DOCS.md` around lines 55 - 60, Reword the two steps
to be goal‑first by leading with the action (e.g., "Send/sync Thread credentials
to your phone") then follow with concise platform-specific steps; for Android,
start with the goal then "On the HA app go to Settings > Companion App >
Troubleshooting > Sync Thread credentials"; for iPhone, start with the goal then
"In the HA app go to Settings > Devices & services, select the Thread
integration, Configure under Services, and tap 'Send credentials to phone' at
the bottom of the preferred network box"; ensure the exact phrases "Sync Thread
credentials" and "Send credentials to phone" remain intact for discoverability.

[agners]

Thank you for your contribution.

However, I'd prefer if we link to the Thread integration documentation instead, this will make it easier to update this documentation once it works differently.

[tyeth]

Appreciate that, any improvement on the current situation would be good. I found the threads docs page too long [even this one], but to be honest it feels a poor experience due to the companion app not syncing for you, after that you're just scrambling for why the open thread border router isn't found by Android. Also reading that if the HA instance had external Bluetooth adapter then could commission thread/matter devices itself without companion app, so why can't it use the pi5 Bluetooth adapter for that [is binary blob use restricted or just lacking driver/HA support]?

…

On Mon, 16 Feb 2026, 20:39 Stefan Agner, ***@***.***> wrote: *agners* left a comment (home-assistant/addons#4428) <#4428 (comment)> Thank you for your contribution. However, I'd prefer if we link to the Thread integration documentation instead <https://www.home-assistant.io/integrations/thread/#to-make-home-assistant-your-first-thread-network>, this will make it easier to update this documentation once it works differently. — Reply to this email directly, view it on GitHub <#4428 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABTBZ4YE4URYDLBGMUASZU34MITIDAVCNFSM6AAAAACVKMB5I6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSMJQGQZDONBZGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[agners]

Appreciate that, any improvement on the current situation would be good. I found the threads docs page too long [even this one], but to be honest it feels a poor experience due to the companion app not syncing for you, after that you're just scrambling for why the open thread border router isn't found by Android.

We had the automatic sync at one point, but it was slow. Since WiFi based Matter devices and users of other BRs didn't require the sync, we opted that direction. But it is less then ideal, and we should reconsider.

I agree, the Thread docs are long. Ultimately, this is a work around for now. I still would prefer to not duplicate documentation here, but simply redirect users to the docs. But it should be prominent, since lots of users fall into it right now, so I'd suggest to add an alert block at the top of the section:

Important

If you use the Android companion app, you have to synchronize the Thread credentials manually. Refer to the Thread Case 1 documentation.