Improve documentation for Associated Domains setup (#46)

I found the original guide a bit hard to follow and accidentally used
the wrong identifiers in the file, which Apple cached. I'm hoping this
rework makes it a bit clearer

Author: Firehed

DOMAINS.md

@@ -1,35 +1,28 @@
-## Setting up Associated Domains
+# Setting up Associated Domains
 
-Native apps require configuring Associated Domains in order to support passkeys.
+Native apps **require** configuring Associated Domains in order to support passkeys.
 This allows a domain to provide an allow-list of apps that may authenticate using a saved passkey or other authenticator.
 
-> [!WARNING]
+> [!IMPORTANT]
 > If you have not configured Associated Domains, all SnapAuth APIs will immediately fail!
+> This involves publishing a JSON file on your domain, and updating a setting in Xcode.
 
+## Xcode
 
 ### Add the Associated Domains capability
 
-> [!TIP]
-> You may have already done this if your existing app supports password autofill.
->
-> Still, fully review this section!
-
-More info:
-
-- https://developer.apple.com/documentation/xcode/supporting-associated-domains
-- https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains
+You may have already done this if your existing app supports password autofill.
+Still, fully review this section!
 
 In XCode, select your root-level project in the Navigator.
 
 Select your Target, and navigate to the Signing & Capabilities tab.
 
 Click `+ Capability` and select `Associated Domains`
 
-> [!WARNING]
-> This capability is restricted on free Apple Developer accounts.
-> Unfortunately, this means you must have a current, paid account to proceed.
-
-<!-- Also, personal accounts might not work? -->
+> [!NOTE]
+> This capability is unavailable on free Apple Developer accounts.
+> Unfortunately, this means you **must have a current, paid account** to proceed.
 
 In the new Associated Domains section, click `+` and add your domain(s):
 
@@ -39,48 +32,73 @@ This should match the `RP ID` from the SnapAuth dashboard.
 
 <!-- Must match exactly? Registrable domain match? -->
 
-### Publish the domain association file
+## Website
+
+### Create (or update) the domain association file
 
 Create the assoication file (or, if you already have one for other capabilities, add this section):
 
 ```json
 {
   "webcredentials": {
     "apps": [
-      "your App ID"
+      "<Team ID>.<Bundle ID>"
     ]
   }
 }
 ```
 
-This file must be served at `https://yourdomain.tld/.well-known/apple-app-site-association`.
-
-`curl https://yourdomain.tld/.well-known/apple-app-site-association` to test it.
+This full string in `apps` will look something like `A5B4C3D2E1.tld.yourdomain.YourAppName`. 
+See below for details.
 
 > [!CAUTION]
 > If you already have a Domain Association file, be sure only to append or merge this change.
 > Do not replace other content in the file, which could lead to breaking other app functionality!
 
-#### Your App ID
+### `Team ID`
 
-Your App ID can be obtained from the Apple developer portal(s):
+> [!WARNING]
+> The `TeamId` is NOT the App ID from App Store Connect, nor is it your personal developer ID.
+> Even if you're registered as an individual developer account, you still have a Team ID.
+>
+> If you publish the incorrect id in this file, you may have to wait a while before being able to proceed.
+> It's cached fairly aggressively by Apple's CDNs, and there's no known way to force a cache bust.
+> See the bottom of this page for a possible workaround.
 
-https://developer.apple.com/account/resources/identifiers/list > Select your app
+This can be found in a few different places with the Apple developer portal.
+Depending on your role and permissions, not all may work.
 
-or
+1) https://developer.apple.com/account/resources/identifiers/list
+  - Select your app
+  - Look near the top for `App ID Prefix`
 
-https://developer.apple.com/account#MembershipDetailsCard > Look for Team ID, and
+2) https://developer.apple.com/account#MembershipDetailsCard
+  - Scroll down to Membership Details
+  - Look for Team ID
 
+3) https://appstoreconnect.apple.com/access/users
+  - Click into your own account
+  - Look for Team ID 
+
+### `Bundle Id`
 XCode > Your app (the root-level object in Navigator) > Targets > (pick one) > General, look for Bundle Identifier
 
-The App ID is the combination of the Team ID (typically 10 characters) and the Bundle ID (typically configured in-app, frequently in reverse-DNS format): `TeamID.BundleID`
 
-This will result in something like `A5B4C3D2E1.tld.yourdomain.YourAppName`
 
-#### Optional: enable SWC Developer Mode
+### Publish the file
+
+This file must be served at `https://yourdomain.tld/.well-known/apple-app-site-association`.
+
+`curl https://yourdomain.tld/.well-known/apple-app-site-association` to test it.
+
+It should be served with an `application/json` `mime-type`, but it's not strictly required.
+Be sure it's not blocked by robots.txt or firewall rules.
+
+
+## Optional: enable SWC Developer Mode
 
 In production applications, Apple caches the Associated Domains file for about a day.
-For local development, you can bypass this cache:
+For local development of a macOS app, you can bypass this cache:
 
 1) _Add_ a second entry to the Associated Domains section:
 `webcredentials:yourdomain.tld?mode=developer`
@@ -96,3 +114,10 @@ sudo swcutil developer-mode -e 1
 You still **must** publish the association file; this only bypasses the cache.
 
 On iOS devices, this is done in Settings.app -> Developer -> Associated Domains Development
+
+## External Resources
+
+More info:
+
+- https://developer.apple.com/documentation/xcode/supporting-associated-domains
+- https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains