docs update

Author: adincebic

apple/apple_archive.bzl

@@ -1,4 +1,4 @@
-# Copyright 2025 The Bazel Authors. All rights reserved.
+# Copyright 2026 The Bazel Authors. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

apple/internal/apple_archive.bzl

@@ -441,10 +441,10 @@ The label to a target to re-package into an Apple archive. For example, an
         "include_symbols": attr.bool(
             default = False,
             doc = """
-    If true, collects `$UUID.symbols`
-    files from all `{binary: .dSYM, ...}` pairs for the application and its
-    dependencies, then packages them under the `Symbols/` directory in the
-    final archive.
+If true, collects generated `$UUID.symbols` files from all `{binary: .dSYM, ...}`
+pairs for the application and its dependencies, then packages them under the
+`Symbols/` directory in the final archive. Symbol files are only available when
+dSYM generation is enabled, such as by passing `--apple_generate_dsym`.
     """,
         ),
     },
@@ -464,7 +464,7 @@ target's unarchived bundle root for IDE consumers.
 Example:
 
 ````starlark
-load("//apple:apple_archive.bzl", "apple_archive")
+load("@rules_apple//apple:apple_archive.bzl", "apple_archive")
 
 ios_application(
     name = "App",

doc/common_info.md

@@ -557,14 +557,15 @@ When using Bazel's remote cache and/or build execution, there are a few flags yo
 We recommend adding the following to your `.bazelrc`:
 
 ```shell
-common --modify_execution_info=^(BundleApp|BundleTreeApp|DsymDwarf|DsymLipo|GenerateAppleSymbolsFile|ObjcBinarySymbolStrip|CppArchive|CppLink|ObjcLink|ProcessAndSign|SignBinary|SwiftArchive|SwiftStdlibCopy)$=+no-remote,^(BundleResources|ImportedDynamicFrameworkProcessor)$=+no-remote-exec
+common --modify_execution_info=^(BundleApp|BundleTreeApp|CreateArchive|CreateCombinedDossierZip|DsymDwarf|DsymLipo|GenerateAppleSymbolsFile|ObjcBinarySymbolStrip|CppArchive|CppLink|ObjcLink|ProcessAndSign|SignBinary|SwiftArchive|SwiftStdlibCopy)$=+no-remote,^(BundleResources|ImportedDynamicFrameworkProcessor)$=+no-remote-exec
 ```
 
 The following table provides a rationale for each mnemonic and tag. In general though, the mnemonics that are excluded in `--modify_execution_info` are excluded because they produce or work on large outputs which change frequently and as such are faster when run locally, or they are not generally configured for remote execution (such as signing).
 
 | Mnemonics | Tag | Rationale |
 | --- | --- | --- |
 | `BundleApp`, `BundleTreeApp`, `ProcessAndSign` | `no-remote` | Produces a large bundle, which is inefficient to upload and download |
+| `CreateArchive`, `CreateCombinedDossierZip` | `no-remote` | Produces large archive outputs, and macOS archive packaging relies on preserving bundle symlinks and modes while walking the tree artifact |
 | `CppArchive`, `CppLink`, `ObjcLink`, `SwiftArchive` | `no-remote` | Linked binaries have local paths, and it's slower to download them versus linking locally |
 | `SwiftStdlibCopy` | `no-remote` | Processing Swift stdlib is a quick file copy of a locally available resource, so it's not worth uploading or downloading |
 | `DsymDwarf`, `DsymLipo`, `GenerateAppleSymbolsFile`| `no-remote-exec` | Processing dSYMs/Symbols remotely requires uploading the linked binary; this could go away if you switch to uploading linked binaries |

doc/rules-apple_archive.md

@@ -26,7 +26,7 @@ target's unarchived bundle root for IDE consumers.
 Example:
 
 ````starlark
-load("//apple:apple_archive.bzl", "apple_archive")
+load("@rules_apple//apple:apple_archive.bzl", "apple_archive")
 
 ios_application(
     name = "App",
@@ -47,6 +47,6 @@ apple_archive(
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="apple_archive-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="apple_archive-bundle"></a>bundle |  The label to a target to re-package into an Apple archive. For example, an `ios_application` or `macos_application` target.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
-| <a id="apple_archive-include_symbols"></a>include_symbols |  If true, collects `$UUID.symbols` files from all `{binary: .dSYM, ...}` pairs for the application and its dependencies, then packages them under the `Symbols/` directory in the final archive.   | Boolean | optional |  `False`  |
+| <a id="apple_archive-include_symbols"></a>include_symbols |  If true, collects generated `$UUID.symbols` files from all `{binary: .dSYM, ...}` pairs for the application and its dependencies, then packages them under the `Symbols/` directory in the final archive. Symbol files are only available when dSYM generation is enabled, such as by passing `--apple_generate_dsym`.   | Boolean | optional |  `False`  |