Backfill repo manifests on main (agent card + per-category READMEs)#313
Merged
Conversation
SEO/GEO audit on aspose-pdf/agentic-net-examples scored Overall 45 (Poor) -- Discovery=0, SEO=38 -- with HIGH-severity findings dominated by "no /.well-known/agent.json", "no AI manifest (llm.txt)", and "0/34 categories have dedicated pages (README.md)." This commit closes those gaps without waiting for the next release cycle: - /.well-known/agent.json -- agent card with capabilities, MCP endpoint, manifests, stats. Lets LangChain hubs / Postman / n8n / agent directories auto-discover the repo. - 34 x <category>/README.md -- the human-facing twin of the existing AGENTS.md, what GitHub renders by default when navigating into the folder. Each carries a keyword-rich SEO lead, example list, and back-links to the category AGENTS.md + root. - llm.txt -- the AI-crawler-discoverable repo summary. Existed in the generator code but never shipped to main. - index.json + AGENTS.md refreshed against the current main snapshot (26.5.0, 2,648 examples, 34 categories). Generated by scripts/regen_main_docs.py (one-shot) running the same generators as the production update_repo_docs path. Re-running the audit after this merges should lift Discovery and SEO into the "Good" range. AI-assisted development
Bugs in the initial agent.json on this branch:
- mcp_endpoint used https:// but production MCP serves only http:// on
port 7002 -- consumers would 404 immediately
- Missing api_base_url, openapi_url, docs_url -- all available on the
PDF MCP at /openapi.json and /docs (verified 200 publicly)
- Missing tools enumeration -- agent directories need this to route
- Categories were just names; per-category example counts let
directory previews show coverage at a glance
New top-level shape: {name, version, url, api_base_url, mcp_endpoint,
openapi_url, docs_url, capabilities, tools, categories: [{name,
examples}], product, links}.
Surfaces the four PDF MCP endpoints (agent_generate, agent_run,
generate, retrieve) so consumers can pick the right entry point
without first crawling /openapi.json.
AI-assisted development
agent-aspose-pdf-examples
force-pushed
the
docs/backfill-manifests-20260624T150441
branch
from
8ff52dd to
34b8657
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the HIGH-severity findings from a SEO/GEO Agent audit on this repo (Overall 45 / Poor, Discovery 0, SEO 38):
/.well-known/agent.json— agent directories / LangChain hubs / Postman / n8n cannot auto-discover the repollm.txt— AI crawlers (ChatGPT, Perplexity, Claude) miss the repo on standard manifest pathsREADME.mdper folder (what GitHub renders by default), notAGENTS.mdChanges
.well-known/agent.jsonllm.txt<category>/README.md× 34index.jsonAGENTS.md(root + several per-cat)73 files changed, 3615 insertions, 214 deletions. No code, tests, or LICENSE.txt touched.
How generated
One-shot run of
scripts/regen_main_docs.pyfrom the aspose-pdf-api-v2 sibling repo, using the same generators as the productionupdate_repo_docspath. The agent-card + per-category README generators are from gitlab MR !48 (pending merge); identical code, just executed standalone here so main doesn't wait for the 26.6.0 release cycle.Test plan
AI-assisted development