Use Mintlify-generated LLM context

[enyst]

Why

We maintain two generated LLM context files to keep legacy V0 documentation out of agent context. Mintlify now supports that exclusion itself: its generated llms.txt and llms-full.txt omit pages with noindex: true, and deleting a custom file restores the generated version.

Sources:

• Mintlify: llms.txt and custom overrides
• Mintlify: indexing controls and their effects

Changes

• Set seo.indexing: "navigable" explicitly in docs.json.
• Add noindex: true to all ten V0 MDX pages and the two former monorepo architecture pages already excluded by the generator.
• Remove llms.txt, llms-full.txt, their generator, weekly sync workflow, generator-specific test, and the Makefile whose only targets regenerated those files.
• Document the policy in README and AGENTS.

Legacy documentation remains readable at its existing URLs and in navigation. No documentation pages are removed or redirected.

Preserve current content

• Add Agent Server Package under SDK → Remote Agent Server.
• Add Browser Session Recording beside Browser Use; correct its recording output path, sync example 38 from current SDK source, and cross-link both guides.
• Copy the six current Canvas conversation-runtime settings into the navigable Canvas Development page and point the v1.20.0 release note there. The original environment-variable page remains unchanged.
• MCP changes and removal/consolidation of documentation pages are deferred to a follow-up.

Behavior to account for

noindex also excludes these pages from site search, sitemaps, external search indexing, and AI assistant context. It is not an LLM-only setting. Do not switch seo.indexing to "all", which opts excluded pages back into the generated LLM files. .mintignore is unsuitable here because it would unpublish the legacy pages.

Mintlify follows navigation instead of scanning every MDX file. The audit identified 16 pages outside navigation. This update adds Agent Server and browser recording to navigation and preserves the current Canvas environment settings in an existing navigable page. The other unlisted pages remain accessible by URL but are omitted as standalone native LLM entries. See the audit comment for the follow-up recommendations.

The 16 pages identified by the original audit

• openhands/usage/about.mdx
• openhands/usage/agents.mdx
• openhands/usage/cloud/project-management/jira-dc-integration.mdx
• openhands/usage/cloud/project-management/linear-integration.mdx
• openhands/usage/cloud/project-management/overview.mdx
• openhands/usage/developers/debugging.mdx
• openhands/usage/developers/development-overview.mdx
• openhands/usage/developers/evaluation-harness.mdx
• openhands/usage/developers/websocket-connection.mdx
• openhands/usage/environment-variables.mdx
• openhands/usage/llms/custom-llm-configs.mdx
• overview/first-projects.mdx
• sdk/arch/agent-server.mdx
• sdk/arch/mcp.mdx
• sdk/arch/sdk.mdx
• sdk/guides/browser-session-recording.mdx

These controls exclude page entries; links or mentions of V0 inside current documentation can still appear in the full text.

Validation

• Confirmed all 12 excluded pages have boolean noindex: true in parsed YAML frontmatter.
• Confirmed only the two intended navigation entries were added, no existing navigation entries or redirects were removed, and MCP is unchanged. Preserved pages are indexable. The recording example exactly matches upstream SDK example 38 and passes Python syntax parsing; Canvas settings were checked against the launcher and Agent Server config.
• Validated the new SEO configuration against Mintlify's current official JSON schema. Full-config validation reports the same pre-existing head property rejection as upstream main; there are no new schema errors.
• git diff --check passes; no stale generator commands remain.
• Attempted mint validate with CLI 4.2.909. It fails before building because os.networkInterfaces() returns uv_interface_addresses: Unknown system error 1 in this environment.

Deployment verification remains necessary: fetch both generated files, check current SDK/Agent Canvas/Cloud/CLI page entries, and verify the 12 excluded pages are absent as entries. Also open a V0 page to confirm it remains accessible.

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Prepared by an AI agent on Astra, helping Engel Nyst (@enyst) with project maintenance.

[enyst]

Follow-up audit of the 16 pages outside navigation, by an AI agent on Astra helping Engel Nyst (@enyst).

We should not add all 16 to navigation. But treating all 16 as expendable would also be a mistake. There is current material worth preserving, particularly browser recording and Agent Server setup. Some pages are already linked from current documentation despite having no sidebar entry.

I compared the pages with the rest of the docs at 450c8a64 and cloned current OpenHands, software-agent-sdk, and benchmarks to check implementation claims. This is a source/content audit; I did not run the examples or verify hosted Cloud integration rollout.

Page-by-page recommendation

Paths below are relative to the docs root. “Retire” means preserve historical access or redirect after checking inbound links, not delete URLs indiscriminately.

Page	Assessment	Navigation / better destination
usage/about	Old introduction: calls CodeActAgent the current default and describes the old project stack.	Retire from current docs. Introduction and Agent architecture cover the subjects more appropriately.
usage/agents	Historical CodeAct explanation and a 2024 demo, not a description of the current agent implementation.	Legacy/research reference only. Use Agent architecture for current behavior.
developers/debugging	Launch configurations target openhands.cli.main, openhands.server.listen, and openhands.core.main. Those module paths are absent from the current OpenHands checkout.	Do not add as-is. Replace with component-specific debugging instructions linked from Canvas Development. Its current source guide is docs/DEVELOPMENT.md.
developers/development-overview	A directory map of the former monorepo, including frontend/, openhands/runtime/, and evaluation/. Not the present repository layout.	Retire/consolidate into Contributing and Canvas Development; explain the separate SDK and benchmarks repositories there.
developers/evaluation-harness	V0 harness: poetry, AppConfig, Runtime, run_controller, and old event imports. Current benchmark setup uses the SDK.	Retire this implementation guide. Link to benchmarks README and the relevant benchmark's own instructions. There is no equivalent current, general benchmark-authoring guide in this docs corpus.
developers/websocket-connection	Documents Socket.IO and oh_event / oh_user_action. Canvas currently opens a native WebSocket on /sockets/events/{conversationId}.	Legacy only. Canvas architecture and SDK events are better conceptual entry points, but do not fully replace a current wire-protocol guide. That is a real documentation gap.
usage/environment-variables	Mixed generations, not simply obsolete. Old defaults (CodeActAgent, RUNTIME=docker, TOML sections) coexist with current Canvas OH_CONVERSATION_* forwarding. Canvas v1.20.0 release notes link here.	Split/update before indexing. Move verified Canvas variables into a navigable Canvas configuration/development reference and keep Agent Server settings scoped separately. Preserve the current Docker-runtime material; do not silently discard it with the old tables.
llms/custom-llm-configs	Old named TOML sections, main.py / cli.py, and draft-editor configuration. Also still linked from the current SDK LLM architecture page.	Legacy only; fix that inbound SDK link. Use Canvas LLM profiles and SDK LLM profile store for current saved model configurations.
project-management/jira-dc-integration	Still titled “Coming soon”; describes Cloud workspace/service-account setup and a fixed webhook URL. The corpus now has a much more specific Enterprise guide with a different setup flow.	Do not promote as a current Cloud guide without verification. For Enterprise, use Jira Data Center. It documents Replicated configuration and connection-specific webhook URLs; this is a different deployment scope, so an unconditional redirect would be misleading.
project-management/linear-integration	“Coming soon” service-account/webhook/OAuth instructions. No equivalent detailed Linear integration guide found in the corpus.	Keep out of current navigation until the Cloud owner verifies availability and setup. If supported, refresh it and add under Cloud → Integrations. Neither its age nor its absence from navigation proves the feature is unavailable.
project-management/overview	“Coming soon” umbrella page asserting availability and shared behavior across Jira Cloud, Jira DC, and Linear.	Rebuild only around verified integrations, or merge into the existing Cloud integrations navigation. Jira Cloud is already navigable; Enterprise Jira has separate guides. Do not use this old overview as evidence of rollout.
overview/first-projects	The incremental prompting exercises remain useful. Product-specific UI/token instructions need reconciliation with today's Canvas/Cloud flows. Already linked by FAQs and Prompting Best Practices, and receives the old start-building redirect.	Preserve the useful material. Merge its beginner progression into Tutorials and redirect/update inbound links, or refresh this page and add it under Home → Get Started. No need for two overlapping tutorial hubs.
sdk/arch/agent-server	Substantially current. CLI startup, indexed session API keys, and workspace directory defaults match the SDK. Multiple current guides link here. Much overlaps Local Agent Server, but it also collects deployment/security/operations guidance.	Preserve in the indexed corpus. Either add under SDK → Agent Server as an operations/package reference, or consolidate its useful extra material into Local Agent Server and update links. Do not classify it as legacy.
sdk/arch/mcp	The sync/async bridge and tool adapter architecture still exist. Needs corrections: MCPToolDefinition lives in tool.py, not the linked definition.py; the emitted action is a data wrapper validated against a generated model, not simply the illustrated subclass. Resource-result handling is also overstated.	Refresh, then add under SDK → Architecture → Components. MCP guide covers usage, not this architectural role. The main MCP overview already links here.
sdk/arch/sdk	Not safe to promote. Says every operation returns a new immutable Conversation and demonstrates conversation.add_message(); current send_message() returns None and updates state. Also makes overly broad security/sandbox-escape prevention claims. The getting-started page links here.	Retire/consolidate into Architecture overview, Conversation, and Security. Update the getting-started link.
guides/browser-session-recording	Current, distinct feature, but stale details. The recording tools and upstream example still exist. The page incorrectly says output follows conversation persistence_dir; implementation writes under .agent_tmp/browser_observations/recording-…/. Its embedded example also lags upstream.	Fix and add beside Browser Use in SDK guides. Browser Use does not cover recording/replay. Refresh from example 38, correct the output path, and cross-link the guides. Follow the repo's agent- guide naming convention if renaming, with a redirect.

Source verification

• Current OpenHands repository / old development paths: README, current development guide. The checkout is the Canvas application; the old Python monorepo modules referenced above are absent.
• WebSocket protocol: native WebSocket construction, event socket URL.
• Current environment settings worth retaining: Canvas forwards the six OH_CONVERSATION_* settings.
• Agent Server configuration: session keys, CORS, and workspace defaults; actual module entry point.
• Conversation semantics: send_message(...)->None and state updates.
• MCP corrections: client bridge, definition and validation, action wrapper and supported result types.
• Browser recording: output directory constant, executor passes it to recording, current example including browser initialization.
• Current evaluation approach: benchmarks setup, SDK-based benchmark implementation.

Cloud limitation: I could not access the Cloud implementation through the available clone/integration paths. Accordingly, the three Cloud rows above are documentation-consistency findings and publication recommendations, not claims that Jira DC or Linear are unsupported. The Enterprise Jira page is a better scoped document in the corpus, not independently verified backend behavior in this audit.

Implication for this PR

I would keep the Mintlify migration, but resolve preservation of current content before merging: browser recording, Agent Server operations, and the current Canvas environment settings should have a navigable home. MCP merits a corrected architecture entry. The other cleanup can be scoped separately, with explicit legacy labeling or redirects and inbound-link updates.

A regular body link to an unlisted page does not put it into docs.json navigation. Several of these pages are therefore discoverable by humans today but still disappear as standalone entries from the proposed native LLM index. The audit changes my earlier “add current pages separately” suggestion: we should make those few preservation decisions deliberately as part of this migration.

[enyst]

Opened the two follow-ups as enyst:

• docs: correct MCP architecture and include it in navigation #816 corrects MCP architecture and adds it to SDK navigation.
• docs: consolidate obsolete pages and label retained legacy references #817 consolidates five superseded pages, preserves their URLs with redirects, and labels five retained references as legacy/noindex. It preserves the beginner prompts in Tutorial Library and leaves the unverified Cloud integration pages intact.

The follow-ups are linked using GitHub's new native stack feature (stack #818): #816 is layer 1/2 and #817 is layer 2/2, each with only its own diff.

There is one GitHub limitation: cross-fork stacks are not supported. This PR's head is in enyst/docs, so #815 cannot be included in the native stack itself. To preserve this PR and its discussion, I created OpenHands/docs:docs/mintlify-native-llms-stack-base at this PR's exact head, 1d6de7c, and based #816 on it.

Merge order remains #815 → #816 → #817. Both follow-ups are drafts: after #815 merges, rebase the follow-up commits onto main and retarget the native stack before merging them. If #815 changes before merging, the stack base and follow-up branches will need updating too.

Source evidence and validation details are in both PR descriptions. Both GitHub link-check workflows have passed.

[all-hands-bot]

Reviewed and verified the core migration against source and Mintlify's own docs. Looks good to merge.

Verified:

• Mintlify's llms.txt/indexing docs confirm the mechanism this PR relies on: noindex: true excludes pages from llms.txt/llms-full.txt as well as site search, sitemaps, and AI context, and seo.indexing defaults to "navigable" (valid enum: navigable | all). The explicit "navigable" setting is the correct, documented default.
• All 10 V0 pages under openhands/usage/v0/ and both former monorepo architecture pages carry boolean noindex: true; no V0*-prefixed pages exist outside that directory.
• docs.json adds exactly the two intended navigation entries (sdk/arch/agent-server, sdk/guides/browser-session-recording), removes no entries or redirects, and all 288 page entries resolve to existing files. Both new nav targets exist, and the new internal links/anchors resolve.
• The browser-session-recording example matches upstream SDK example 38 byte-for-byte; BROWSER_RECORDING_OUTPUT_DIR (.agent_tmp/browser_observations) and the six OH_CONVERSATION_* variables match software-agent-sdk and dev-safe.mjs. The make build in sync-agent-sdk-openapi.yml targets the agent-sdk submodule, so removing the root Makefile is safe; no stale references to the generator remain.

Non-blocking notes:

• This is a real behavior change beyond LLM context: pages without navigation drop out of the generated index (the old generator scanned every MDX file), and noindex also removes the legacy pages from search engines/sitemaps. The follow-ups (#816 MCP, #817 consolidation/redirects) restore the remaining current material, so the #815 → #816 → #817 order matters.
• Worth confirming after deploy that /llms.txt and /llms-full.txt contain the current SDK/Agent Canvas/Cloud/CLI entries and omit the 12 excluded pages.

This review was posted by an AI agent (OpenHands) on behalf of the requester.