Align JavaScript SDK documentation with the Java SDK's structure and Conductor-agent terminology

.github/workflows/agent-e2e.yml

@@ -5,7 +5,7 @@ name: Agent E2E
 # /agent/* control plane + TaskDef.runtimeMetadata persistence (conductor-oss
 # PR #1255) and the agent runtime on by default from 3.32.0-rc.8 onward.
 # The Agentspan server JAR is no longer used as a server flavor here; the
-# Agentspan CLI binary is still downloaded (its own separate pin) since the
+# external `agentspan` CLI binary is still downloaded (its own separate pin) since the
 # CLI/skill e2e suites still drive it against this same server.
 # Port of the Python SDK's proven agent-e2e workflow; JS deltas only
 # (Node toolchain, jest runner; Python kept solely for mcp-testkit).
@@ -21,7 +21,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  AGENTSPAN_CLI_VERSION: "0.4.4"        # pinned CLI release — independent of the server
+  CONDUCTOR_AGENT_CLI_VERSION: "0.4.4"        # pinned CLI release — independent of the server
   CONDUCTOR_OSS_VERSION: "3.32.0-rc.8"  # pinned conductor-oss release — bump deliberately
 
 jobs:
@@ -31,8 +31,8 @@ jobs:
     env:
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      AGENTSPAN_SERVER_URL: http://localhost:8080/api
-      AGENTSPAN_CLI_PATH: ${{ github.workspace }}/agentspan
+      CONDUCTOR_AGENT_SERVER_URL: http://localhost:8080/api
+      CONDUCTOR_AGENT_CLI_PATH: ${{ github.workspace }}/agentspan
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -69,13 +69,13 @@ jobs:
           curl -sfL "https://repo1.maven.org/maven2/org/conductoross/conductor-server/${CONDUCTOR_OSS_VERSION}/conductor-server-${CONDUCTOR_OSS_VERSION}-boot.jar" \
             --output conductor-server-boot.jar
 
-      # Agentspan CLI (CLI/skill suites) — kept on its own separate pin,
+      # External `agentspan` CLI (CLI/skill suites) — kept on its own separate pin,
       # independent of which server JAR is under test.
       - name: Download CLI binary from release
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release download "v${AGENTSPAN_CLI_VERSION}" --repo agentspan-ai/agentspan \
+          gh release download "v${CONDUCTOR_AGENT_CLI_VERSION}" --repo agentspan-ai/agentspan \
             --pattern "agentspan_linux_amd64" --output agentspan
           chmod +x agentspan
 

.github/workflows/pull_request.yml

@@ -12,6 +12,58 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Documentation validation. Deliberately one fast job rather than folded into
+  # the unit-test matrix, where every check would run three times identically.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate documentation links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --offline --no-progress README.md docs
+          fail: true
+
+      - name: Reject retired documentation references
+        run: |
+          # Retired paths and constructs that must not come back.
+          #
+          # Deliberately does NOT reject docs/agents/api-reference.md or
+          # docs/agents/index.md: java-sdk retires those, but we keep
+          # api-reference.md as a redirect stub (as python-sdk does) so inbound
+          # links keep resolving. See docs/documentation-parity.md.
+          if grep -REn 'docs/agents/agent-(runtime-api|client-api|structure|schema)\.md|docs/agents/generated|docs/testing_framework\.md|conductor\.netflix\.com' README.md docs; then
+            echo "Documentation references a retired path or renderer-specific construct."
+            exit 1
+          fi
+
+      - name: Reject pre-rebrand configuration names outside the migration guide
+        run: |
+          # AGENTSPAN_* must not be presented as the way to configure the SDK.
+          # docs/upgrading.md and docs/compatibility.md document the deprecation
+          # itself, and the reference pages name the deprecated export aliases,
+          # so those are allowed to mention them.
+          if grep -REn 'AGENTSPAN_[A-Z]' README.md docs \
+               --exclude=upgrading.md --exclude=compatibility.md; then
+            echo "AGENTSPAN_* appears outside the migration guide."
+            echo "Use CONDUCTOR_AGENT_* — see docs/upgrading.md."
+            exit 1
+          fi
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Verify agent configuration schema
+        run: npm run verify:agent-schema
+
   linter:
     runs-on: ubuntu-latest
     steps:

AGENTS.md

@@ -40,14 +40,14 @@ src/open-api/                    # OpenAPI layer
   types.ts                       # Extended types - add custom fields here
 src/integration-tests/           # E2E tests against real Conductor server
   utils/                         # waitForWorkflowStatus, executeWorkflowWithRetry, etc.
-src/agents/                      # Durable agent layer (merged Agentspan TS SDK)
+src/agents/                      # Durable agent layer (merged Conductor TS SDK)
   index.ts                       # Agent, AgentRuntime, tool, guardrails, handoffs, ...
   frameworks/                    # LangGraph/LangChain/generic serializers + detection
   testing/                       # Agent testing toolkit (/agents/testing subpath)
   wrappers/                      # Vercel AI / LangGraph / LangChain drop-in wrappers
   __tests__/                     # Colocated jest unit tests (picked up by test:unit)
-e2e/                             # Agent e2e suites vs live agentspan server (jest.e2e.config.mjs)
-cli-bin/                         # agentspan CLI helper scripts (Go CLI walk-up probe target)
+e2e/                             # Agent e2e suites vs live Conductor server (jest.e2e.config.mjs)
+cli-bin/                         # Conductor CLI helper scripts (Go CLI walk-up probe target)
 examples/agents/                 # Agent examples (own tsconfig; run via npx tsx)
 docs/agents/                     # Agent layer documentation
 ```
@@ -76,9 +76,28 @@ docs/agents/                     # Agent layer documentation
   Framework subdirs (adk/, langgraph/, openai/, vercel-ai/) install their own
   deps (`scripts/install-example-deps.sh`); `examples/agents` is excluded from
   the root tsconfig.
-- `AGENTSPAN_*` env vars (`AGENTSPAN_SERVER_URL`, default
-  `http://localhost:8080/api`) are the agent layer's config surface — kept
-  working as-is; `CONDUCTOR_*` aliases are a possible follow-up.
+- `CONDUCTOR_AGENT_*` env vars (`CONDUCTOR_AGENT_SERVER_URL`, default
+  `http://localhost:8080/api`) are the agent layer's config surface. The
+  previous `AGENTSPAN_*` spelling still resolves as a deprecated fallback and
+  warns once per name per process — see `src/agents/legacy-env.ts`, the
+  duplicated helper in `resolveOrkesConfig.ts`, and `e2e/helpers.ts`.
+
+### Names that are NOT ours to rename
+
+The Agentspan → Conductor rebrand deliberately left these alone. They are
+externally owned, and renaming them points users at things that don't exist or
+breaks interop. Do not "clean these up":
+
+| Name | Owner |
+|---|---|
+| `__agentspan_ctx__`, `__agentspan_sdk__.cjs`, `_agentspan.llm`/`.model`/`.framework`/`.tools`, `_agentspan_human_task`, `_agentspan_human_prompt` | cross-SDK wire keys / Go CLI probe target — same server compile path as the Python SDK |
+| `agentspan.embedded`, `agentspan.default-context-window` | orkes-conductor server boot properties |
+| `agentspan-ai/agentspan`, `agentspan/codingexamples`, `agentspan-server` | external GitHub repos and container image |
+| `agentspan_linux_amd64`, the `agentspan` CLI binary, `agentspan deploy`/`credentials`/`login`/`import` | the external CLI's release asset and command surface |
+| `agentspan <= 0.4.2`, `agentspan server > 0.4.2` | version-qualified references to the upstream product — renaming makes them factually false |
+
+Every cross-SDK wire key is underscore-prefixed; that invariant is the quickest
+way to tell a wire contract from our own prose.
 
 ## Commands
 
@@ -94,9 +113,9 @@ CONDUCTOR_AUTH_KEY=key CONDUCTOR_AUTH_SECRET=secret \
 ORKES_BACKEND_VERSION=5 \
 npm run test:integration:orkes-v5
 
-# Agent e2e (requires a running agentspan server + LLM keys; CI does this
+# Agent e2e (requires a running Conductor server + LLM keys; CI does this
 # against the pinned release JAR — see .github/workflows/agent-e2e.yml)
-AGENTSPAN_SERVER_URL=http://localhost:8080/api npm run test:agent-e2e
+CONDUCTOR_AGENT_SERVER_URL=http://localhost:8080/api npm run test:agent-e2e
 ```
 
 ## Post-Change Verification (Required)
@@ -251,14 +270,23 @@ public async someMethod(args): Promise<T> {
 
 ## Documentation Maintenance
 
-### Metrics Documentation (METRICS.md)
+### Metrics Documentation (docs/observability.md)
 
 When adding, removing, or renaming metrics in `src/sdk/worker/metrics/`:
 1. Update both `LegacyMetricsCollector.ts` and `CanonicalMetricsCollector.ts` (or add a no-op stub in the collector that does not emit the metric)
 2. Ensure `toPrometheusText()` and the corresponding `PrometheusRegistry` / `CanonicalPrometheusRegistry` are updated in sync — missing a metric in either causes silent data loss
-3. Update `METRICS.md` to reflect the change in both the legacy and canonical catalog tables
+3. Update `docs/observability.md` to reflect the change in both the legacy and canonical catalog tables (the "Metric reference" section). Root `METRICS.md` is now a redirect stub — don't add content there.
 4. Add or update the corresponding direct recording method documentation if applicable
 
+### Documentation structure
+
+Docs follow the canonical layout shared with the Java and Python SDKs:
+`docs/*.md` plus `docs/agents/{concepts,frameworks,reference}/`. See
+`docs/documentation-standard.md` for the page shape and terminology, and
+`docs/documentation-parity.md` for the cross-SDK mapping and CI checks.
+`docs/agents/*.md` and `docs/api-reference/*.md` are redirect stubs kept for
+inbound links — don't add content to them, and don't delete them.
+
 ### SDK_NEW_LANGUAGE_GUIDE.md
 
 When adding new client methods, builders, worker features, or examples:

BREAKING_CHANGES.md

@@ -1,5 +1,66 @@
 # Breaking Changes
 
+## Unreleased (Agentspan → Conductor rebrand)
+
+### `AGENTSPAN_*` environment variables renamed to `CONDUCTOR_AGENT_*`
+
+**Change:** every `AGENTSPAN_<NAME>` env var is now `CONDUCTOR_AGENT_<NAME>` —
+`AGENTSPAN_SERVER_URL` → `CONDUCTOR_AGENT_SERVER_URL`, and likewise for
+`AUTH_KEY`, `AUTH_SECRET`, `LLM_MODEL`, `LOG_LEVEL`, `CLI_PATH`,
+`WORKER_POLL_INTERVAL`, `WORKER_THREADS`, `AUTO_START_WORKERS`,
+`STREAMING_ENABLED`, and the three `LIVENESS_*` knobs.
+
+**Why:** the agent layer was merged in from the Agentspan TS SDK, which has
+since been rebranded to Conductor. This aligns the config surface with the
+Python and Java SDKs.
+
+**Impact:**
+
+| Scenario | Before | After | Breaks? |
+|----------|--------|-------|---------|
+| `CONDUCTOR_AGENT_SERVER_URL` set | Ignored | Used | **No** |
+| `AGENTSPAN_SERVER_URL` set | Used | Used, warns once per process | **No** |
+| Both set | — | `CONDUCTOR_AGENT_*` wins | **No** |
+| Custom `ConductorLogger` without `warn` | — | Deprecation goes to `info` | **No** |
+
+**Migration:** rename the variables. The old names keep working as deprecated
+fallbacks and will be removed in a future release; each one warns once per
+process the first time it actually supplies a value. `AGENTSPAN_LOG_LEVEL`
+falls back silently — warning there would mean logging through the logger whose
+level is still being resolved.
+
+The precedence chain (spec R3) is unchanged apart from the new tier:
+`CONDUCTOR_*` env → explicit config → `CONDUCTOR_AGENT_*` env →
+`AGENTSPAN_*` env (deprecated) → `http://localhost:8080`.
+
+### `AgentspanError` renamed to `ConductorAgentError`
+
+**Change:** the base class of the agent error hierarchy is now
+`ConductorAgentError`. `AgentspanError` remains exported as a deprecated alias.
+`AgentspanMetadata` (from `./agents/langchain` and `./agents/langgraph`) is
+likewise aliased to `ConductorAgentMetadata`.
+
+**Impact:**
+
+| Scenario | Before | After | Breaks? |
+|----------|--------|-------|---------|
+| `import { AgentspanError }` | Works | Works, marked `@deprecated` | **No** |
+| `catch (e) { e instanceof AgentspanError }` | Works | Works — alias is the same class object, not a subclass | **No** |
+| `const e: AgentspanError` (type position) | Works | Works — value and type alias both exported | **No** |
+| `err.name` on a base-class instance | `"AgentspanError"` | `"ConductorAgentError"` | **Yes** if asserted on |
+
+**Migration:** switch to `ConductorAgentError`. The only observable change for
+existing code is `error.name` on a base-class instance, which now reports the
+canonical name — assertions on that string need updating.
+
+### Names deliberately NOT renamed
+
+Cross-SDK wire keys (`__agentspan_ctx__`, `_agentspan.llm`, …), orkes-conductor
+server boot properties (`agentspan.embedded`), the external `agentspan` CLI and
+its subcommands, external repos/npm scopes (`agentspan-ai/agentspan`,
+`@agentspan-ai`), and version-qualified references to the upstream product
+(`agentspan <= 0.4.2`) are unchanged. See the table in `AGENTS.md`.
+
 ## v3.x (Worker Architecture Parity Release)
 
 ### `TaskHandler.startWorkers()` is now `async`