docs: complete public API documentation and normalize license headers

samples/src/main/java/dev/openan/workflow/engine/examples/config/WorkbenchClientProperties.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.config;
 

samples/src/main/java/dev/openan/workflow/engine/examples/demo/A2ATProtocolCases.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.demo;
 

samples/src/main/java/dev/openan/workflow/engine/examples/demo/EmbeddedOmcSupport.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.demo;
 

samples/src/main/java/dev/openan/workflow/engine/examples/demo/HostQuickStart.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.demo;
 

samples/src/main/java/dev/openan/workflow/engine/examples/demo/SpnCasePrompts.java

@@ -50,8 +50,8 @@ private SpnCasePrompts() {}
 
   /**
    * JSON schema for the private-line complaint data, mirroring the SDK's bundled slot schema
-   * ({@code Task-T/network-layer/private-line-complaint/v1}): 任务对象 identifies the line, 任务上下文
-   * carries the complaint context.
+   * ({@code Task-T/network-layer/private-line-complaint/v1}): the task-object slot identifies
+   * the line and the task-context slot carries the complaint context.
    */
   public static Map<String, Object> privateLineComplaintSchema() {
     return SdkSlotSchemaLoader.loadConfigured(StandardTemplates.PRIVATE_LINE_COMPLAINT);
@@ -193,7 +193,10 @@ public static boolean injectNegotiation(String stepName, boolean enabled) {
   // Authorization-T (spec case 7.5: add authorization policy)
   // ------------------------------------------------------------------
 
-  /** Schema mirroring the SDK's Authorization-T slot schema (授权策略的操作类型 + 策略列表). */
+  /**
+   * Schema mirroring the SDK's Authorization-T slot schema: the operation-type slot selects the
+   * authorization operation and the policy-list slot carries the policies to grant.
+   */
   public static Map<String, Object> authorizationSchema() {
     return SdkSlotSchemaLoader.loadConfigured(StandardTemplates.AUTHORIZATION_POLICY_MANAGEMENT);
   }

samples/src/main/java/dev/openan/workflow/engine/examples/extension/AuthorizationPolicy.java

@@ -3,6 +3,18 @@
  * All Rights Reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.extension;
 

samples/src/main/java/dev/openan/workflow/engine/examples/extension/NotificationPolicy.java

@@ -3,6 +3,18 @@
  * All Rights Reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.extension;
 

samples/src/main/java/dev/openan/workflow/engine/examples/extension/SdkSlotSchemaLoader.java

@@ -3,6 +3,18 @@
  * All Rights Reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.extension;
 

samples/src/main/java/dev/openan/workflow/engine/examples/server/LocalServerAddress.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.server;
 

samples/src/main/java/dev/openan/workflow/engine/examples/util/LlmHelper.java

@@ -50,6 +50,21 @@ public final class LlmHelper {
 
   private LlmHelper() {}
 
+  /**
+   * Calls the configured OpenAI-compatible chat API and returns the reply text.
+   *
+   * <p>Demo-only degradation contract: when the LLM is not configured or disabled, the HTTP call
+   * returns a non-200 status, the reply is empty or incomplete (a non-null {@code finishReason}
+   * other than {@code stop}), or the call throws, this method returns {@code fallback} and logs
+   * an {@code LLM_FALLBACK} line. The return type carries no signal distinguishing a real reply
+   * from the fallback, so callers report success either way. Production code should treat
+   * generation failure as a business failure instead of adopting this pattern.
+   *
+   * @param envPath path to the .env file holding the LLM configuration
+   * @param system system prompt, may be null
+   * @param user user prompt
+   * @param fallback text returned on any failure; see the degradation contract above
+   */
   public static String text(String envPath, String system, String user, String fallback) {
     Config config = resolve(envPath);
     if (config == null) {

samples/src/main/java/dev/openan/workflow/engine/examples/workbench/ExecutionCancellation.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.workbench;
 

samples/src/main/java/dev/openan/workflow/engine/examples/workbench/SpringWorkbenchExtensionLifecycle.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.workbench;
 

samples/src/main/java/dev/openan/workflow/engine/examples/workbench/StaleTaskCleaner.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.workbench;
 

samples/src/main/java/dev/openan/workflow/engine/examples/workbench/WorkbenchAgentCatalog.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.workbench;
 

samples/src/main/java/dev/openan/workflow/engine/examples/workbench/WorkbenchExtensionLifecycle.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.workbench;
 

samples/src/main/java/dev/openan/workflow/engine/examples/workbench/WorkbenchTaskInputParser.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.workbench;
 

samples/src/test/java/dev/openan/workflow/engine/examples/SpnCrossCityE2ETest.java

@@ -3,8 +3,19 @@
  * All Rights Reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
-
 package dev.openan.workflow.engine.examples;
 
 import static org.junit.jupiter.api.Assertions.*;

samples/src/test/java/dev/openan/workflow/engine/examples/demo/DocumentedCallbackExampleTest.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.demo;
 

samples/src/test/java/dev/openan/workflow/engine/examples/demo/EmbeddedOmcSupportTest.java

@@ -1,6 +1,20 @@
 /*
  * Copyright (c) 2026 Huawei Technologies Co., Ltd.
+ * All Rights Reserved.
+ *
  * SPDX-License-Identifier: Apache-2.0
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *    not use this file except in compliance with the License. You may obtain
+ *    a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ *    License for the specific language governing permissions and limitations
+ *    under the License.
  */
 package dev.openan.workflow.engine.examples.demo;