Port's llms.txt is useful, but it can provide far more context than an agent needs for a specific task, which means unnecessary token usage. I would like Port's documentation to expose a lightweight, hierarchical index that lets LLMs progressively discover the right documentation instead of loading a large representation of the docs upfront. For example, an agent trying to understand GitHub mappings should be able to follow a path like: Docs → Integrations → GitHub → Mapping → Relevant documentation page Each level would only need enough information to help the model decide which branch to follow. For example, a root index could conceptually contain: { "sections": [ { "name": "Software Catalog", "description": "Blueprints, entities, relations and catalog modelling", "index": "..." }, { "name": "Self-service", "description": "Actions, workflows and developer self-service", "index": "..." }, { "name": "Integrations", "description": "GitHub, Jira, Kubernetes, cloud providers and other integrations", "index": "..." } ] } The Integrations index would then expose its children, and so on until the agent reaches the relevant page. This does not have to be JSON. JSON is only one possible implementation. The important part is providing a stable, machine-readable, hierarchical way for agents to understand: What documentation sections exist What each section/page is about What child topics exist underneath it Where to go next for a particular topic Which actual documentation page contains the detailed information Individual pages could also expose short intent hints such as: Use this page for: - Creating GitHub resource mappings - Mapping repositories into Port entities - Configuring JQ mappings This would help an agent distinguish between similarly named sections without reading the full page. The goal is progressive context loading. Instead of: Agent → load llms.txt → receive a large amount of documentation context → search through it the agent could do: Agent → load small docs index → select Integrations → select GitHub → select Mapping → load only the relevant documentation This would reduce token usage, reduce irrelevant context, and make Port's documentation easier for coding agents and long-running AI workflows to navigate. I think this becomes especially useful for tasks like: > "Build this portal using Port." An agent working on that task may need to consult the documentation repeatedly. Giving it a small semantic tree to navigate would be much more efficient than repeatedly loading broad documentation context. llms.txt can still remain as the broad-context option. This would complement it with a more token-efficient discovery mechanism.
