Please select the area the issue is related to
Gateway, CLI
Please select the aspect the issue is related to
Aspect/AI (AI/LLM integration, MCP, AI readiness)
Suggested Feature
Several frameworks now bundle their own documentation directly inside the installed project so AI coding agents can read accurate, version matched reference material locally instead of relying on stale training data. Next.js ships its full docs as plain markdown inside the installed package, with a short AGENTS.md that tells agents to read those docs before writing code, plus an llms.txt index for agents that fetch docs over the network instead of reading local files.
Vercel published eval results comparing this approach against a skills based setup on Next.js 16 APIs not covered in model training data (https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals). An 8KB compressed docs index embedded directly in AGENTS.md reached a 100 percent pass rate. Skills reached only 53 percent, matching the no docs baseline, until an explicit system prompt instruction was added telling the agent to explore the project first and then invoke the skill, which raised it to 79 percent. Vercel also found that a larger, more exhaustive AGENTS.md (around 40KB) performed worse than the compressed 8KB version, and recommend writing short, curated content that prevents common mistakes rather than comprehensive documentation. Next.js has since retired its old knowledge skills in favor of the bundled docs, keeping skills only for interactive workflows that need a live feedback loop, such as driving a browser or reading a running dev server.
Zuplo, which is also an API gateway product, follows the same pattern. Its docs are bundled inside the installed package, its AGENTS.md contains one instruction to read those docs first, and its CLAUDE.md imports AGENTS.md directly so both stay in sync from a single source.
The WSO2 gateway release scaffolds (api-gateway and ai-gateway, which share an identical base structure) are currently obtained with a plain curl and unzip, and ship with no documentation at all. Custom policy authoring and config.toml key reference material exist only on external pages, some of which return empty content when fetched by a tool rather than a browser.
This proposal follows the Next.js and Zuplo pattern for the docs content itself, but the installation flow is presented as a decision between two options rather than a single prescribed path.
-
Option A: bundle by default. The docs, AGENTS.md, and CLAUDE.md are included in every release download automatically, matching how Next.js and Zuplo ship them today. Simpler to build and maintain, since there is only one artifact and no branching install logic. The tradeoff is added download size and repo footprint for anyone who is not using an AI agent with this project.
-
Option B: interactive opt in install script. Replace the plain curl and unzip step with a small install script, similar in spirit to how create-next-app offers an --agents-md flag during scaffolding rather than always including it. The script would ask something like:
Set up this project for AI coding agents? (adds AGENTS.md and local docs) [Y/n]
If yes, it writes AGENTS.md and CLAUDE.md and fetches the docs bundle described below. If no, the release extracts exactly as it does today, with no added footprint. This keeps the addition fully opt in and gives a natural place to ask follow up questions later, such as which agent tool is in use or whether to fetch the full docs set versus just the compact index. The tradeoff is one more moving part to build, test, and keep working across platforms.
Either option solves the underlying problem described below. Which one to build is a decision for the platform team to make, based on how much of the download footprint and build complexity tradeoff matters versus keeping the change as simple as possible to ship.
An MCP server is not recommended for this under either option. It would add a running process and a connection to configure for no benefit over files that are already local. Skills are also not proposed here, since Vercel's evals found skills only reached parity with a plain compressed docs file after adding explicit trigger instructions, and Next.js has since retired its own knowledge skills in favor of bundled docs, reserving skills for interactive workflows that need a live feedback loop rather than static reference material.
Proposed structure
The structure below reflects Option B, the interactive install script, since it is the more involved of the two. Under Option A the same end state (AGENTS.md, CLAUDE.md, docs) would simply be present unconditionally in the extracted release, with no install.sh step.
wso2apip-{api,ai}-gateway-1.1.0/
├── install.sh (Option B only, replaces plain curl + unzip)
├── AGENTS.md (Option A: always present. Option B: only if opted in)
├── CLAUDE.md (imports AGENTS.md; same conditions as above)
├── docs/ (same conditions as above)
│ ├── llms.txt (index of all bundled docs)
│ ├── policies/
│ │ ├── authoring-guide.md (Base Policy Interface, phase modes, factory function, build.yaml registration, known pitfalls)
│ │ └── reference-policy/ (one minimal, working, commented example policy)
│ └── config/
│ └── schema.md (every config.toml key, purpose, required or optional, default)
├── configs/ (unchanged)
├── observability/ (unchanged)
├── resources/ (unchanged)
└── build.yaml / build-manifest.yaml / docker-compose.yaml
AGENTS.md stays short, following the Next.js and Zuplo model, and Vercel's own finding that a compressed index outperforms a large file. It should contain a compact index of the bundled docs plus one instruction telling the agent to read the relevant file under docs/ before writing or configuring anything, not the full reference content inline.
docs/policies/authoring-guide.md covers the custom policy contract directly, including the pitfalls that already cost real debugging time in practice, such as a Ballerina.toml flow keyword not matching an implemented stub causing a compile error, or a distribution version mismatch with the SDK.
docs/config/schema.md documents every config.toml key across all policies, including the embedding and vector database keys required by Semantic Cache. This directly addresses the class of failure described in the Semantic Cache bug report, where an undocumented required key caused a full proxy outage with no warning at save or deploy time.
Related Issues
No response
Steps to Verify
Please select the area the issue is related to
Gateway, CLI
Please select the aspect the issue is related to
Aspect/AI (AI/LLM integration, MCP, AI readiness)
Suggested Feature
Several frameworks now bundle their own documentation directly inside the installed project so AI coding agents can read accurate, version matched reference material locally instead of relying on stale training data. Next.js ships its full docs as plain markdown inside the installed package, with a short AGENTS.md that tells agents to read those docs before writing code, plus an llms.txt index for agents that fetch docs over the network instead of reading local files.
Vercel published eval results comparing this approach against a skills based setup on Next.js 16 APIs not covered in model training data (https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals). An 8KB compressed docs index embedded directly in AGENTS.md reached a 100 percent pass rate. Skills reached only 53 percent, matching the no docs baseline, until an explicit system prompt instruction was added telling the agent to explore the project first and then invoke the skill, which raised it to 79 percent. Vercel also found that a larger, more exhaustive AGENTS.md (around 40KB) performed worse than the compressed 8KB version, and recommend writing short, curated content that prevents common mistakes rather than comprehensive documentation. Next.js has since retired its old knowledge skills in favor of the bundled docs, keeping skills only for interactive workflows that need a live feedback loop, such as driving a browser or reading a running dev server.
Zuplo, which is also an API gateway product, follows the same pattern. Its docs are bundled inside the installed package, its AGENTS.md contains one instruction to read those docs first, and its CLAUDE.md imports AGENTS.md directly so both stay in sync from a single source.
The WSO2 gateway release scaffolds (api-gateway and ai-gateway, which share an identical base structure) are currently obtained with a plain curl and unzip, and ship with no documentation at all. Custom policy authoring and config.toml key reference material exist only on external pages, some of which return empty content when fetched by a tool rather than a browser.
This proposal follows the Next.js and Zuplo pattern for the docs content itself, but the installation flow is presented as a decision between two options rather than a single prescribed path.
Option A: bundle by default. The docs, AGENTS.md, and CLAUDE.md are included in every release download automatically, matching how Next.js and Zuplo ship them today. Simpler to build and maintain, since there is only one artifact and no branching install logic. The tradeoff is added download size and repo footprint for anyone who is not using an AI agent with this project.
Option B: interactive opt in install script. Replace the plain curl and unzip step with a small install script, similar in spirit to how
create-next-appoffers an--agents-mdflag during scaffolding rather than always including it. The script would ask something like:If yes, it writes AGENTS.md and CLAUDE.md and fetches the docs bundle described below. If no, the release extracts exactly as it does today, with no added footprint. This keeps the addition fully opt in and gives a natural place to ask follow up questions later, such as which agent tool is in use or whether to fetch the full docs set versus just the compact index. The tradeoff is one more moving part to build, test, and keep working across platforms.
Either option solves the underlying problem described below. Which one to build is a decision for the platform team to make, based on how much of the download footprint and build complexity tradeoff matters versus keeping the change as simple as possible to ship.
An MCP server is not recommended for this under either option. It would add a running process and a connection to configure for no benefit over files that are already local. Skills are also not proposed here, since Vercel's evals found skills only reached parity with a plain compressed docs file after adding explicit trigger instructions, and Next.js has since retired its own knowledge skills in favor of bundled docs, reserving skills for interactive workflows that need a live feedback loop rather than static reference material.
Proposed structure
The structure below reflects Option B, the interactive install script, since it is the more involved of the two. Under Option A the same end state (AGENTS.md, CLAUDE.md, docs) would simply be present unconditionally in the extracted release, with no install.sh step.
AGENTS.md stays short, following the Next.js and Zuplo model, and Vercel's own finding that a compressed index outperforms a large file. It should contain a compact index of the bundled docs plus one instruction telling the agent to read the relevant file under
docs/before writing or configuring anything, not the full reference content inline.docs/policies/authoring-guide.md covers the custom policy contract directly, including the pitfalls that already cost real debugging time in practice, such as a Ballerina.toml flow keyword not matching an implemented stub causing a compile error, or a distribution version mismatch with the SDK.
docs/config/schema.md documents every config.toml key across all policies, including the embedding and vector database keys required by Semantic Cache. This directly addresses the class of failure described in the Semantic Cache bug report, where an undocumented required key caused a full proxy outage with no warning at save or deploy time.
Related Issues
No response
Steps to Verify