docs: build the published site from develop (#408)

[Paulo Lacerda (placerda)]

What this changes

docs/ currently lives on two diverging branches:

• the orphan docs branch, which is what GitHub Pages actually builds from
• the copy on develop / main, which README.md, CONTRIBUTING.md, and four modules under src/agentops/ link into

Every documentation fix therefore needs two pull requests, and the two trees had drifted apart on eight files. That is issue #408.

This PR makes develop the single source, and points the Pages build at it.

Why develop and not main

main only ever receives merges from release/vX.Y.Z. Building the site from main would mean a one-character typo fix could not reach the published site without cutting a release, tagging it, and writing a changelog entry.

develop is the branch every fix PR squashes into. Building from develop means a documentation-only PR publishes as soon as it merges. No release, no tag, no changelog.

main still receives docs/ through the normal release merge, so every existing link into the default branch keeps resolving. Nothing had to be deleted to make this work.

Reconciling the eight diverged files

Taken file by file, on which version was actually correct:

File	Kept	Reason
concepts.md	docs	Strict superset.
doctor-explained.md	docs	Superset; the develop pre-flight section was also factually wrong about when checks run.
how-it-works.md	docs	Superset.
release-process.md	develop	Newer. Its ../CONTRIBUTING.md link resolved from the repo root but not from the rendered site, so it is now absolute.
e2e-live-setup.md	docs + port	Two blocks that existed only on develop restored.
ci-github-actions.md	docs + port	The Migration section existed only on develop.
evaluation.md	docs + port	Three sections existed only on develop.
tutorial-prompt-agent.md	docs	Verified both subsections that appeared dropped are in fact present.

Documentation bugs fixed along the way

These were found by running the examples against the code, not by reading them. All four are live on the published site today.

evaluation.md documented privacy.redact_pii. That field does not exist on TelemetryPrivacyConfig, and the model sets extra="forbid", so the example failed to load. Replaced with the real redact_fields and max_field_length.

evaluation.md showed agentops telemetry import without --apply. Without that flag the command is a dry run and writes nothing, so the step could not produce the dataset the following step consumed.

evaluation.md described a replay_url field on imported rows. No such field is emitted. Rewrote the paragraph against the telemetry block that is actually produced.

tutorial-hosted-agent.md had a config that cannot load. It paired a placeholder endpoint carrying no Foundry domain with protocol: responses. AgentOps classifies endpoints by domain, not by path, so a non-Foundry host is restricted to http-json and the config was rejected. The placeholder now carries the real host shape, and the constraint is stated, because it was documented nowhere.

Other cleanup

tutorial-hosted-agent-quickstart.md is removed. It covered hosted and HTTP agents in one file; the docs branch had already split it into tutorial-hosted-agent.md and tutorial-http-agent.md with better coverage of each. All five inbound references now point at the correct one of the two.

tutorial-end-to-end.md is added to the nav. It was orphaned from the site while being referenced from the README and from src/agentops/agent/checks/errors.py.

bundles.md is excluded from the build. It is marked pre-1.0 historical reference and nothing links to it.

Three internal links pointed at files that exist on no branch. Fixed.

site/ added to .gitignore so a local mkdocs build stops showing up as untracked.

Workflow change

deploy-docs.yml now triggers on push to develop, filtered to the paths that can affect the rendered site, and runs mkdocs build --strict as its own step before gh-deploy so a broken build fails before it publishes. A concurrency group with cancel-in-progress stops overlapping runs from racing each other onto gh-pages.

The release: published trigger is kept, because main.py resolves the latest release through the GitHub API at build time and the site needs to rebuild when that changes.

Verification

Check	Result
mkdocs build --strict	24 pages, 0 warnings
Every complete agentops.yaml example instantiated against AgentOpsConfig	21 configs, 0 failures
CLI commands in docs checked against the Typer app	23 files, 0 real issues
CLI flags checked against the Typer app	34 files, 0 invalid flags
Internal .md links	resolved
docs/*.md references from outside docs/	283 files scanned, 2 broken found and fixed
External links	43 checked; the only two failures are docs.pypi.org returning HTTP 429 to this IP, confirmed reachable by hand

Follow-up

The release trigger resolves its workflow file from the default branch, so it will keep using the old deploy-docs.yml until the next release carries this file to main. A companion PR targets main directly with just that file.

Once this is merged and the site is confirmed to be serving from develop, the orphan docs branch can be deleted. That is a separate, destructive step and is not part of this PR.

Refs #397, #405, #408