docs: align documentation with Java/Python SDK structure; remove all Agentspan naming (breaking)

[ambiorix2099]

Pull Request type

• Bugfix
• Feature
• Refactoring (no functional changes, no api changes)
• Build related changes
• WHOSUSING.md
• Other (please describe): Documentation restructure to match the Java/Python SDK layout, plus a breaking removal of all Agentspan naming (env vars and public type names).

NOTE: Please remember to run ./gradlew spotlessApply to fix any format violations.

Changes in this PR

Describe the new behavior from this PR, and why it's needed

Issue # (no tracking issue; ports the intent of python-sdk#441)

⚠️ Breaking change — action required

All Agentspan naming owned by this SDK is removed, with no environment-variable
aliases and no [Obsolete] type shims. Per the convention already in CHANGELOG.md,
this must ship as a minor or major version bump, never a patch.

Removed	Replacement	Failure mode if missed
AGENTSPAN_* env vars (8 agent knobs + 3 connection settings)	CONDUCTOR_AGENT_* / CONDUCTOR_*	⚠️ Silent — see below
AgentspanException	ConductorAgentException	Compile error
AgentspanJson	ConductorAgentJson	Compile error
OTel source agentspan.agents	conductor.agents	Dashboards filtering the literal stop matching

The two failure modes are not equivalent, and reviewers should weigh this. A renamed
type is a compile error — safe and impossible to miss. A removed env var is not: an
unrecognised variable is indistinguishable from an unset one, so a missed rename surfaces
as unexpected default behaviour rather than an error. Someone running with
AGENTSPAN_WORKER_THREADS=16 silently drops to 1 thread. docs/upgrading.md leads with
this and supplies a grep to find stragglers.

Note also that the connection aliases predate this PR. AGENTSPAN_SERVER_URL /
_AUTH_KEY / _AUTH_SECRET were already shipped and documented in a prior CHANGELOG
entry, so removing them affects anyone who migrated from Agentspan and never updated
their config — a wider blast radius than this branch's own changes.

Why

conductor-oss/java-sdk is the canonical documentation structure, and python-sdk#441 adopted it. This repo was behind it: of the 43 doc files that PR added, this repo had none — no concepts/, frameworks/, or reference/ subdirectories, and none of the top-level topic docs. Java's CI actively rejects docs/agents/api-reference.md as a retired path, and this repo had that file.

The terminology half of the driver was equally real: 648 case-insensitive agentspan occurrences across 212 files, and 421 AGENTSPAN_* references.

What changed

Commit	Content
602ec8f	44 new doc files: 21 top-level, 11 concepts/, 6 frameworks/, 6 reference/
5fca471	Seven superseded pages gutted to redirect stubs (−2,039 lines)
b00ecc5	Agent runtime env vars → CONDUCTOR_AGENT_*
163104d	Bugfix: blank connection env vars no longer clobber the fallback chain
c05037e	Merge main, carrying the server-driven guardrail content into the new locations
3556498	Examples + e2e naming sweep, 183 files
c50b648	CONTEXT.md glossary entry + ADR-0001
58fd00c	Review feedback: remove all Agentspan naming — no backward compatibility

Env var naming. Eight AgentConfig knobs renamed to CONDUCTOR_AGENT_*, matching Java and Python. Two prefixes coexist deliberately: connection settings stay CONDUCTOR_* because they are shared with the core SDK; these knobs configure only the agent layer.

Bugfix (the Bugfix box above). AgentRuntime.BuildConfiguration chained with ??, which falls back only on null. On Unix, export CONDUCTOR_SERVER_URL= produced BasePath="" instead of falling through to the default. CHANGELOG had claimed this was already fixed since the connection rename; it wasn't, and had no test. Now fixed via a FirstNonBlank helper and covered by tests.

Build related. .github/workflows/agent-e2e.yml env block updated to the new variable names.

One name that is load-bearing and was NOT renamed

__agentspan_ctx__ is a task-input key the SDK only ever reads — the server writes it. It is part of the wire contract for ToolContext injection, so renaming it would have silently broken tool context delivery with no compile error and no test failure. It is now called out in the ADR, CHANGELOG, upgrading.md, and CONTEXT.md so nobody "finishes the job" later.

Also untouched, being outside this SDK's control: the agentspan CLI (21 refs), the agentspan-ai GitHub org and its repos (8), and server properties such as agentspan.default-context-window. Renaming these in docs would point users at things that may not exist. Note: if the agentspan-ai org has already been renamed, several credential examples are already broken on main — pre-existing, not caused here.

Two upstream claims that did not survive verification

1. python-sdk#441's description claims it "kept legacy runtime environment-variable aliases for backward compatibility." Its diff deletes every AGENTSPAN_* read, and its config docstring reads "Only CONDUCTOR_AGENT_* settings are supported." The docstring is the accurate one. This SDK now matches that actual behaviour, and goes further by renaming the public types too.
2. A blind AGENTSPAN_ → CONDUCTOR_ sweep left a merged bug upstream: os.getenv("CONDUCTOR_SERVER_URL") or os.getenv("CONDUCTOR_SERVER_URL") — the same variable read twice, silently dropping legacy support.

My own sweep reproduced that second bug character-for-character in Examples/Shared/Settings.cs; it was caught and rewritten.

agentspan.embedded=true — a server-side boot property — appears zero times in this repo, so there was nothing to mishandle.

Deviations worth reviewer attention

• frameworks/semantic-kernel.md added beyond the Python set. That adapter is .NET-only and is documented today in framework-agents.md; writing only Python's five files would have destroyed existing content.
• Four status-banner stubs — schema-client.md, langchain.md, langgraph.md, claude-agent-sdk.md. The functionality does not exist in .NET, so each says so plainly and points at the nearest supported path rather than describing absent features.
• observability.md is metrics.md verbatim, verified byte-identical before the original was gutted.
• ~17 top-level core-SDK docs are new authoring from the SDK source, not relocation — this repo previously documented the core SDK only in README.md and two files under docs/readme/. This is where review effort is best spent. Three API names written from memory (Skill.LoadAll, DynamicForkTask, and the onFail default) turned out wrong when checked against source; there is no link checker or schema verifier here to catch the next one.
• One pre-existing doc error corrected: the old api-reference.md documented OnFail onFail = Retry for both guardrail factories, but the code defaults to OnFail.Raise before and after main's changes.

Verification

• CI Build fully green on 58fd00c — lint, unit_tests, integration_tests, build_ai_examples, legacy_integration_tests. build_ai_examples passing means all 175 example projects still compile after the type rename, which is the change most likely to have broken something.
• Agent E2E green and not vacuous on 58fd00c: 157 tests, 155 passed, 2 skipped — identical counts to the pre-removal run on c50b648. This is the evidence that matters most for the alias removal: E2eFixture now reads only CONDUCTOR_SERVER_URL, so if the workflow env and the fixture had drifted apart, the availability probe would have failed, every suite would have skipped, and the run would still have reported green. Matching counts confirm the suites genuinely reached a live server through the new variable alone.
• Tests assert the removal positively — LegacyAgentspanName_IsIgnored, LegacyAgentspanServerUrl_IsIgnored, LegacyAgentspanAuthPair_IsIgnored, plus a per-knob sweep confirming every legacy name yields the default. Re-introducing a fallback fails the build rather than passing quietly.
• All 254 relative links under docs/ verified to resolve; agent-schema.json verified to parse.

Known gap

No documentation validation was added. Java enforces link checking, a retired-reference grep, and a schema verifier in CI; this repo has none. This is not theoretical: agent-schema.json went stale within hours of being written when main changed AgentConfigSerializer's guardrail serialization, and only a manual re-check caught it. Recorded in docs/documentation-parity.md.

Alternatives considered

Describe alternative implementation you have considered

1. Keep the AGENTSPAN_* env aliases. This is what the branch originally shipped, and ADR-0001 was written to justify it: a fallback chain costs one line per knob, while dropping it costs every existing deployment's configuration. Reversed in review ("no backward compatibility"), because a partial rebrand leaves two names for one setting indefinitely and every reader has to learn which is canonical. The ADR was rewritten rather than amended, since its central section was "Why the aliases stayed".

2. Rename the types behind an [Obsolete] shim. Insert ConductorAgentException as a new base with AgentspanException : ConductorAgentException marked [Obsolete], so both catch clauses keep working. Rejected for the same reason as the aliases: permanent obsolete surface in the public API to spare a one-line edit in consumer code. A compile error is the right failure mode here — unlike the env vars, this one cannot fail silently.

3. Rename __agentspan_ctx__ too, for a literally complete sweep. Rejected on evidence: the SDK only reads that key, so the server writes it. Renaming would break ToolContext injection silently.

4. One prefix everywhere (CONDUCTOR_* for the runtime knobs too). Internally the most consistent, but it diverges from Java and Python, and would imply either that the core SDK reads worker-liveness knobs or that the agent layer owns the connection settings. Cross-SDK parity won.

5. Delete the superseded doc pages instead of stubbing them. Cleaner final tree and unambiguously satisfies Java's ban on docs/agents/api-reference.md, but breaks every inbound link. Python's own precedent was to gut rather than delete (writing-agents.md went +6/−477), so stubs it is — each carrying a was/now table so a stale link lands on the specific section, not a directory index.

6. Mirror Python's file set verbatim, with no semantic-kernel.md. Rejected because it would silently drop existing documentation for an adapter this SDK actually ships.

7. Add the doc validation now (lychee + retired-reference grep as CI steps, schema contract as xUnit tests). Deferred deliberately to keep this PR reviewable; the gap is documented rather than left implicit.

8. Fix the blank-env-var defect in a separate PR. Considered, since it touches shared core-SDK connection resolution rather than the agent layer. Included here because the fix is small and this PR's docs would otherwise have had to describe behaviour known to be wrong.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests	3.31% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.