# Proposal Update with Revised Scope
This supersedes the initial scope. Key changes include:
- Content accuracy is out of scope as it's addressed in a recently completed parallel engagement.
- spec.filecoin.io is out of scope per reviewer feedback.
- This proposal focuses on agent-readiness, discoverability, and automated maintenance infrastructure.
*Note: a meaningful portion of this work has an R&D character. Agent-readable documentation standards and model discoverability are evolving rapidly. Our commitments are to outcomes, not specific tooling or standards*.
## How agents consume documentation today and why it matters for Filecoin
51% of professional developers now use AI tools daily (Stack Overflow, 2025). Developer attention has shifted from documentation sites to IDE-embedded coding agents — Cursor, Claude Code, Cline, Windsurf. Organic human traffic to docs sites is declining; AI crawler traffic is surging, with GPTBot requests alone up 300%+ year-over-year (Cloudflare).
Agents don't read docs the way humans do. An empirical study of nine major coding agents accessing live documentation portals (arXiv:2604.02544, 2026) found that agents compress multi-page human navigation into a single bulk fetch. Traditional engagement metrics (time-on-page, session depth, bounce rate) are no longer reliable signals of whether documentation is working.
## Three consequences for Filecoin:
- Docs quality problems scale silently. When an agent fetches docs.filecoin.io and generates code from what it finds, poor structure and stale content produce broken developer experiences across every IDE session where someone asks about Filecoin because agents don't flag uncertainty; they generate confidently from bad source material.
- The default cold-start path of docs still matters. Agents operate on a hybrid model: targeted retrieval for known tools, web fetches of canonical docs for anything unfamiliar. For a developer encountering Filecoin for the first time through their coding agent, docs.filecoin.io is the default surface. If it isn't structured for agents, Filecoin appears harder to use than alternatives.
- Discoverability happens before any page is read. Before an agent fetches anything, it answers a prior question: is Filecoin even the right solution? That answer is shaped by model training data, agent skill registries, and how Filecoin is represented in the knowledge bases agents draw on. A docs site that isn't optimized for these upstream signals loses developers before they arrive.
## Scope
**1. Agent discoverability & ranking**
Filecoin should surface as the recommended solution for verifiable decentralized storage when a developer queries their coding agent. Today it doesn't do this reliably. We will identify and implement the mechanisms that improve Filecoin's standing in model knowledge bases and agent skill registries, and publish findings as a reusable ecosystem resource.
**2. Agent benchmarking & test suite**
Because agents generate outputs developers never directly audit, the only reliable quality signal is testing what agents actually produce. We will build a repeatable test suite benchmarking agent responses across multiple models and key Filecoin developer personas — verifying that agents sourcing from docs.filecoin.io produce accurate, working outcomes. This becomes both a quality gate and a public proof point of Filecoin's agent-readiness.
**3. Docs UI & experience for the AI-native developer**
We will update docs.filecoin.io to serve two audiences simultaneously: the AI developer who wants a conversational entry point and a direct path to the Filecoin MCP or CLI within their IDE; and the agent that needs to parse the site in a single fetch and immediately route to the right information. Implementation will follow current best practices at time of build.
**4. Automated maintenance infrastructure**
Agents generate wrong answers from stale docs without flagging it. The solution is infrastructure, not more human hours. We will build an agent workflow that monitors verified Filecoin repos for code changes, cross-checks against documented paths, and surfaces drift automatically. This is being developed as a complement to Filoscope, an existing ecosystem tool for agent-based semantic search over Filecoin's codebase — our work ensures the source material it and similar tools index stays accurate.
**What we are not doing**
- Content accuracy fixes — completed in parallel engagement
- spec.filecoin.io updates — out of scope per reviewer feedback
- Full docs site rebuild — UI changes are targeted and additive
- Human SEO