Description

Issue Report: Kilo docs deep-link discovery fails for AI agents (404s on legacy paths and root llms.txt, no redirects)

• Repository: Kilo-Org/kilocode
• Type: Documentation / discoverability bug
• Component: kilo.ai docs site (packages/kilo-docs)
• Reporter context: Seen during real Kilo CLI/agent usage on 2026-09-09 (Windows). Submitting on user's behalf.

Summary

When an AI agent is instructed to "gather information from Kilo docs at https://kilo.ai/docs", resolved doc subpages via legacy URL patterns and received bare 404s from both kilo.ai and kilocode.ai. The 404 responses provide no redirects and no pointer to the current doc index, and the standard machine-readable discovery file is missing at the site root. This makes agents guess stale deep links and burn tool calls / surface errors to users.

Reproduction (verified 2026-09-09)

The same pages now live at paths such as /docs/customize/agent-permissions, /docs/customize/custom-rules — with no redirect from any old form.

Impact

1. Link rot after docs IA migration. Any bookmarks, blog posts, README links, search-engine results, or LLM-training-time memory pointing at /docs/advanced-config/* or /docs/features/* now fail silently. Since model training data contains the old URL structure, agents following the documented deep links will systematically hit 404.
2. Agent discovery path is non-standard. llms.txt at the site root is the de-facto convention for agent-readable docs. Having it only under /docs/llms.txt means a tool instructed only "fetch docs at https://kilo.ai/docs" is likely to try the root file first and 404.
3. Bare 404 bodies. The 404 responses do not return the docs index URL or an equivalent-page suggestion that a fetcher could follow in one hop.

Expected behavior

• HTTP 301/308 redirects from legacy paths (at minimum the well-known ones: /docs/advanced-config/*, /docs/features/*, /docs/mcp/*, /docs/basic-usage/*, /docs/getting-started/* moved sections) to their current locations.
• Old kilocode.ai/kilocode.ai/docs/* domain paths redirect to kilo.ai equivalents (domain-migration UX).
• https://kilo.ai/llms.txt serves (or redirects to) https://kilo.ai/docs/llms.txt.

Possible fix approach

• Add a redirect map in the docs host (Next.js/Mintlify-style _redirects / next.config redirects) generated automatically from the file-move history when the docs IA was reorganized — a git-rename-based mapping would keep it exhaustive.
• Serve a root-level llms.txt.
• (Nice-to-have) Have the 404 template embed the canonical /docs index link so fetch-based agents can self-recover.

Additional note (not a product defect, but relevant context)

In the observed session, the agent also guessed the two /docs/... URLs from parametric memory instead of crawling the index first — a model-behavior mistake on our side. However, the docs-side gaps above are what make this failure mode high-probability across all agent integrations that are told "check https://kilo.ai/docs", and the docs even ship a "Using Kilo Docs with Agents" page, so agent-facing robustness seems in scope. Making the happy path (index → llms.txt → redirect) trivially discoverable would materially reduce these 404s.

Environment

• Kilo CLI / VS Code extension doc-fetch flow, Windows 11, 2026-09-09
• URLs above verified with HTTPS GET (markdown/text fetch mode)

Plugins

No response

Kilo version

No response

Steps to reproduce

No response

Screenshot and/or share link

No response

Operating System

No response

Terminal

No response