Enhance task module documentation with CAD compatibility details and BIS task prerequisites

arma/server/addons/task/README.md

@@ -68,9 +68,11 @@ Mission designers can create tasks in four ways:
 - Eden modules for editor-authored tasks.
 - `fnc_startTask.sqf` for script-authored tasks.
 - `fnc_handler.sqf` for pre-registered entities with reputation gating and
-  ownership binding.
+  ownership binding. This path expects the BIS task and catalog entry to
+  already exist if map-task and CAD visibility are required.
 - Direct task function calls for server-owned or mission-authored flows that
-  intentionally fall back to the `default` org.
+  intentionally fall back to the `default` org. This path expects the BIS task
+  to already exist if map-task visibility is required.
 
 The dynamic mission manager can also generate attack tasks from config. That is
 system-generated content rather than a hand-authored task creation path.
@@ -89,10 +91,26 @@ CAD-compatible creation paths:
 Limited or incompatible paths:
 - `fnc_handler.sqf`: only compatible if a catalog entry was already registered
   elsewhere. The handler sets active status and ownership, but it does not
-  create the BIS task or upsert the catalog entry
+  create the BIS task shown in the map task tab or upsert the catalog entry
 - direct task function calls: not CAD-compatible by default. They bypass
   `fnc_startTask.sqf` and usually do not register the task catalog entry or
-  active status that CAD hydrates from
+  active status that CAD hydrates from. They also only call
+  `BIS_fnc_taskSetState` at completion/failure; they do not create the BIS task
+  first
+
+### BIS Map Task Prerequisite
+Only the Eden task modules and `fnc_startTask.sqf` create the BIS task
+automatically through `BIS_fnc_taskCreate`.
+
+If a mission uses `fnc_handler.sqf` directly or calls a task flow function such
+as `forge_server_task_fnc_attack`, the mission must create a BIS task with the
+same task ID before the Forge task completes. Otherwise the success/failure
+`BIS_fnc_taskSetState` call has no visible map task to update.
+
+That prerequisite can be satisfied with a vanilla Eden task creation module or
+a scripted `BIS_fnc_taskCreate` call. `fnc_startTask.sqf` is the preferred Forge
+path because it handles BIS task creation, Forge catalog registration, entity
+registration, and handler dispatch together.
 
 ### Create With Eden Modules
 Eden task modules are the normal designer-facing path. Place the module,
@@ -142,6 +160,8 @@ creates the BIS task, stores the catalog entry, and dispatches through
 
 ### Start Through The Handler
 Use the handler when you want reputation gating and task ownership binding.
+Create the BIS task and catalog entry separately if this task should appear in
+the map task tab or CAD.
 
 ```sqf
 ["attack", ["task_attack_1", 1, 2, 1500000, -75, 375, false, false], 250, getPlayerUID player] call forge_server_task_fnc_handler;
@@ -156,6 +176,7 @@ Arguments:
 
 ### Start Task Functions Directly
 Direct task calls still work, but they do not provide a requester UID. That means task ownership falls back to the `default` org.
+Create the BIS task separately if this task should appear in the map task tab.
 
 Use direct starts only when that behavior is intended, such as:
 - mission-authored tasks

docs/TASK_USAGE_GUIDE.md

@@ -133,9 +133,11 @@ Mission designers can create tasks in four ways:
 - Eden modules for editor-authored tasks.
 - `forge_server_task_fnc_startTask` for script-authored tasks.
 - `forge_server_task_fnc_handler` for pre-registered entities with reputation
-  gating and ownership binding.
+  gating and ownership binding. This path expects the BIS task and catalog
+  entry to already exist if map-task and CAD visibility are required.
 - Direct task function calls for server-owned or mission-authored flows that
-  intentionally fall back to the `default` org.
+  intentionally fall back to the `default` org. This path expects the BIS task
+  to already exist if map-task visibility is required.
 
 The dynamic mission manager can also generate attack tasks from config. That is
 system-generated content rather than a hand-authored task creation path.
@@ -158,10 +160,27 @@ Limited or incompatible paths:
 
 - `forge_server_task_fnc_handler`: only compatible if a catalog entry was
   already registered elsewhere. The handler sets active status and ownership,
-  but it does not create the BIS task or upsert the catalog entry.
+  but it does not create the BIS task shown in the map task tab or upsert the
+  catalog entry.
 - Direct task function calls: not CAD-compatible by default. They bypass
   `startTask` and usually do not register the task catalog entry or active
-  status that CAD hydrates from.
+  status that CAD hydrates from. They also only call `BIS_fnc_taskSetState` at
+  completion/failure; they do not create the BIS task first.
+
+## BIS Map Task Prerequisite
+
+Only the Eden task modules and `forge_server_task_fnc_startTask` create the BIS
+task automatically through `BIS_fnc_taskCreate`.
+
+If a mission uses `forge_server_task_fnc_handler` directly or calls a task flow
+function such as `forge_server_task_fnc_attack`, the mission must create a BIS
+task with the same task ID before the Forge task completes. Otherwise the
+success/failure `BIS_fnc_taskSetState` call has no visible map task to update.
+
+That prerequisite can be satisfied with a vanilla Eden task creation module or
+a scripted `BIS_fnc_taskCreate` call. `forge_server_task_fnc_startTask` is the
+preferred Forge path because it handles BIS task creation, Forge catalog
+registration, entity registration, and handler dispatch together.
 
 ## Eden Modules
 
@@ -216,7 +235,9 @@ through `forge_server_task_fnc_handler`.
 ## Handler Calls
 
 Use `forge_server_task_fnc_handler` directly when the task entities are already
-registered and you want reputation gating plus ownership binding:
+registered and you want reputation gating plus ownership binding. Create the
+BIS task and catalog entry separately if this task should appear in the map
+task tab or CAD:
 
 ```sqf
 [
@@ -231,7 +252,8 @@ registered and you want reputation gating plus ownership binding:
 
 Direct task function calls still work for mission-authored or server-owned
 tasks, but they do not provide a requester UID. Ownership falls back to the
-`default` org.
+`default` org. Create the BIS task separately if this task should appear in the
+map task tab.
 
 ## Timer Semantics