docs: add Java/Python parity map and guard legacy branding

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Validate documentation links
         uses: lycheeverse/lychee-action@v2
         with:
-          args: --offline --no-progress README.md docs
+          args: --offline --no-progress --include-fragments README.md docs
 
       - name: Reject retired documentation references
         run: |
@@ -41,6 +41,22 @@ jobs:
             exit 1
           fi
 
+      - name: Reject legacy product branding
+        run: |
+          # Scans the whole tree, not just docs/, because the legacy name also
+          # reached shell and Java comments. The pattern uses a character class
+          # so this workflow file does not match itself.
+          #
+          # Excluded: the `<legacy>.embedded` server boot flag. That property is
+          # owned by orkes-conductor, not this SDK — renaming it here would
+          # document a flag that may not exist upstream.
+          if grep -rIn -iE 'agent[s]pan' . \
+               --exclude-dir=.git --exclude-dir=build --exclude-dir=.gradle \
+               | grep -viE 'agent[s]pan\.embedded'; then
+            echo "Legacy product branding found — use Conductor terminology."
+            exit 1
+          fi
+
       - name: Validate documented source links and test-server version
         run: |
           curl --fail --silent --show-error --location --retry 3 --retry-all-errors --output /dev/null \

conductor-client-ai/src/main/java/org/conductoross/conductor/ai/tools/McpTool.java

@@ -111,7 +111,7 @@ public ToolDef build() {
             }
 
             Map<String, Object> config = new HashMap<>(additionalConfig);
-            // AgentSpan's MCP compiler consumes snake_case config keys, matching the
+            // The server's MCP compiler consumes snake_case config keys, matching the
             // cross-SDK agent schema. Using serverUrl silently drops the MCP server
             // from the compiled workflow.
             if (serverUrl != null) config.put("server_url", serverUrl);

docs/README.md

@@ -46,3 +46,4 @@ Build durable workflow workers and AI agents with Conductor. This repository doc
 - Runnable commands link to maintained examples and state an expected result. Short Java blocks labeled **Fragment** need surrounding application setup and link to a complete path.
 - Provider credentials belong on the **Conductor server**, not only in the Java client process. Never place secrets in workflow input or source control.
 - Primary guide authors follow the [documentation standard](documentation-standard.md).
+- Maintainers keeping this tree aligned with the Python SDK follow the [documentation parity map](documentation-parity.md).

docs/documentation-parity.md

@@ -0,0 +1,74 @@
+# Documentation parity: Java and Python SDKs
+
+**Audience:** maintainers keeping the Java and Python SDK documentation aligned. **Prerequisites:** none.
+
+The Java and Python SDKs share one documentation information architecture, so a reader moving between languages finds the same guides in the same places. This page records where the two trees agree, where they deliberately diverge, and which gaps are real work rather than intentional differences.
+
+The counterpart page in the Python SDK is `docs/documentation-parity.md` in [conductor-oss/python-sdk](https://github.com/conductor-oss/python-sdk).
+
+**Snapshot date:** 2026-07-28. Re-verify before relying on the divergence tables; the shared sets change as either SDK adds guides.
+
+## How to use this page
+
+- Adding a guide to a shared set below? Add it to both SDKs, or record it here as an intentional divergence with a reason.
+- Porting documentation between SDKs? Check the direction first. This architecture originated in the Java SDK, so a Python change that cites "alignment with the Java SDK" is usually Python catching up, not a change to mirror back. Diff the file lists before writing anything.
+- Language-idiomatic names are expected to differ (`langchain4j` here, `langchain` there). Only the *concept* needs to exist in both.
+
+## Shared sets
+
+These are identical in both SDKs, filename for filename. Treat them as a contract.
+
+| Set | Files |
+|---|---|
+| Core guides (`docs/*.md`) | `api-map`, `compatibility`, `connection-authentication`, `core-quickstart`, `debugging`, `deployment-scaling`, `documentation-standard`, `examples`, `observability`, `README`, `reliability`, `schedules-events`, `schema-client`, `security`, `server-setup`, `upgrading`, `workers`, `workflow-lifecycle`, `workflow-testing`, `workflows` |
+| Agent concepts (`docs/agents/concepts/*.md`) | `agents`, `callbacks`, `deploy-serve-run`, `guardrails`, `multi-agent`, `scheduling`, `stateful`, `streaming-hitl`, `structured-output`, `termination`, `tools` |
+| Agent reference (`docs/agents/reference/`) | `agent-definition.md`, `agent-schema.md`, `agent-schema.json`, `api.md`, `client.md`, `runtime.md` |
+| Agent hub | `docs/agents/README.md`, `docs/agents/getting-started.md` |
+
+The published [agent schema](agents/reference/agent-schema.md) and its `agent-schema.json` artifact are a cross-SDK wire contract, not just documentation. Both SDKs ship the same schema and both verify it in CI.
+
+## Java-only, by design
+
+| Page | Why Python has no counterpart |
+|---|---|
+| [Files](file-client.md) | `FileClient` is a Java-only client surface. |
+| [Spring Boot selector](spring-boot.md) and [agent Spring Boot](agents/spring-boot.md) | Spring is a JVM framework; there is no Python analogue. |
+
+## Python-only
+
+Paths below are relative to the Python SDK's `docs/` directory.
+
+| Page | Status |
+|---|---|
+| `workflow-message-queue.md` | Real gap. No Java counterpart yet. |
+| `agents/frameworks/claude-agent-sdk.md` | Real gap. Python bridges the Claude Agent SDK; Java has no equivalent bridge. |
+| `AUTHORIZATION.md`, `INTEGRATION.md`, `METADATA.md`, `PROMPT.md`, `SCHEDULE.md`, `SECRET_MANAGEMENT.md`, `TASK_MANAGEMENT.md`, `WORKER.md`, `WORKFLOW.md`, `WORKFLOW_TESTING.md`, `LEASE_EXTENSION.md` | Not gaps. Pre-existing Python pages that the shared lowercase guides superseded. |
+| `agents/advanced.md`, `agents/api-reference.md`, `agents/framework-agents.md`, `agents/writing-agents.md` | Not gaps. Superseded by the shared `concepts/` and `reference/` sets. The agent API-reference page is a path this repo's CI guard explicitly retires. |
+
+## Framework bridges
+
+Both SDKs document the same bridges under `docs/agents/frameworks/`, using each language's own package naming.
+
+| Bridge | Java | Python |
+|---|---|---|
+| Google ADK | [`google-adk.md`](agents/frameworks/google-adk.md) | `google-adk.md` |
+| OpenAI Agents style | [`openai.md`](agents/frameworks/openai.md) | `openai.md` |
+| LangChain | [`langchain4j.md`](agents/frameworks/langchain4j.md) | `langchain.md` |
+| LangGraph | [`langgraph4j.md`](agents/frameworks/langgraph4j.md) | `langgraph.md` |
+| Claude Agent SDK | — | `claude-agent-sdk.md` |
+
+## Expected result
+
+After reading this page you can tell, for any documentation change, whether it needs a matching change in the sibling SDK. If a page you are adding belongs to a shared set and has no counterpart, either add the counterpart or add a row above explaining why it is Java-only.
+
+## Common failure modes
+
+- **Porting in the wrong direction.** A sibling PR titled "align with the Java SDK" is Python adopting this structure. Porting it back here is mostly a no-op — verify with a file-list diff first.
+- **Mirroring a claim instead of the diff.** Sibling PR descriptions can overstate what the code does, particularly around backward-compatibility aliases. Read the diff.
+- **Renaming externally-owned settings.** Server boot properties belong to the Conductor server, not this SDK. Renaming one in these docs points readers at a flag that may not exist.
+
+## Next steps
+
+- [Documentation standard](documentation-standard.md) — what every primary guide must contain.
+- [Compatibility matrix](compatibility.md) — supported server and JDK versions.
+- [API map](api-map.md) — generated Javadocs as the signature source of truth.

e2e/release/package-e2e-bundle.sh

@@ -7,9 +7,8 @@ set -euo pipefail
 # org.conductoross:conductor-client-ai:<version> artifact (no SDK source vendored).
 #
 # Downstream repos (e.g. orkes-io/orkes-conductor) download the bundle from
-# the java-sdk GitHub release and run it against their own server build. This
-# replaces the agentspan-sdk-e2e-java-* bundles formerly cut from
-# agentspan-ai/agentspan — java-sdk is now the canonical home of these suites.
+# the java-sdk GitHub release and run it against their own server build.
+# java-sdk is the canonical home of these suites.
 #
 # Usage:
 #   ./e2e/release/package-e2e-bundle.sh --version 6.0.0 [--out DIR]
@@ -170,8 +169,7 @@ Self-contained end-to-end tests for the Conductor Java agent SDK, pinned to
 release **@VERSION@**. Resolves `org.conductoross:conductor-client-ai:@VERSION@` from
 Maven Central — no SDK source is vendored. Cut from
 [conductor-oss/java-sdk](https://github.com/conductor-oss/java-sdk)
-(`e2e/`); supersedes the `agentspan-sdk-e2e-java-*` bundles
-formerly released from agentspan-ai/agentspan.
+(`e2e/`), the canonical home of these suites.
 
 ## Prerequisites (you provide these)