{
  "name": "git-top",
  "title": "Git.Top GitHub Knowledge Layer for AI Agents",
  "description": "Agent-native open source project intelligence with trust-first discovery, search, project lookup, alternatives, deployment signals, quality scores, and graph reasoning.",
  "protocol_version": "2025-06-18",
  "endpoint": "/mcp/core",
  "profile": "core",
  "profiles": {
    "core": {
      "endpoint": "/mcp/core",
      "tool_count": 5,
      "purpose": "Focused project selection with the smallest useful tool surface."
    },
    "full": {
      "endpoint": "/mcp",
      "tool_count": 21,
      "purpose": "Complete discovery, graph, quality, governance, and reasoning surface."
    }
  },
  "docs_url": "https://git.top/docs",
  "openapi_url": "https://git.top/openapi.json",
  "api_openapi_url": "https://git.top/api/openapi.json",
  "schema_url": "https://git.top/api/schema/project.v2",
  "health_url": "https://git.top/api/health",
  "trust_url": "https://git.top/api/trust",
  "quality_url": "https://git.top/api/quality",
  "agent_map_url": "https://git.top/api/agent-map",
  "agent_map": {
    "name": "Git.Top Agent Surface Map",
    "positioning": "The Knowledge Graph of Open Source",
    "purpose": "Map human pages to REST endpoints, MCP tools, output fields, and trust fields so agents can choose the right Git.Top surface.",
    "production_base_url": "https://git.top",
    "rest_base_url": "https://git.top/api",
    "mcp_endpoint": "https://git.top/mcp",
    "mcp_core_endpoint": "https://git.top/mcp/core",
    "connect_url": "https://git.top/connect",
    "compatibility_url": "https://git.top/compatibility",
    "compatibility_api_url": "https://git.top/api/compatibility",
    "distribution_url": "https://git.top/distribution.json",
    "installable_skill": {
      "name": "git-top-project-selection",
      "repository": "https://github.com/haocn-ops/git-top",
      "path": "skills/git-top-project-selection"
    },
    "openapi_url": "https://git.top/openapi.json",
    "schema_url": "https://git.top/api/schema/project.v2",
    "llms_url": "https://git.top/llms.txt",
    "llms_full_url": "https://git.top/llms-full.txt",
    "roadmap_url": "https://git.top/roadmap",
    "short_path": [
      {
        "step": 1,
        "concept": "Trust preflight",
        "rest": [
          "GET /api/health",
          "GET /api/trust"
        ],
        "mcp_tools": [
          "get_trust_gate"
        ],
        "inspect": [
          "db=available",
          "metadata.source=d1",
          "decision",
          "production_ready"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.reason",
          "sync.freshness",
          "quality.risk_level"
        ],
        "use_when": "Start here before any high-confidence production answer."
      },
      {
        "step": 2,
        "concept": "Discovery",
        "rest": [
          "GET /api/agent-map",
          "GET /api/quickstart",
          "GET /api/workflow"
        ],
        "mcp_tools": [
          "get_agent_workflow",
          "get_atlas"
        ],
        "inspect": [
          "core_surfaces",
          "recommended_agent_flow",
          "recommended_sequence",
          "shortlist"
        ],
        "trust_fields": [
          "trust_policy.strict_mode",
          "trust_policy.disclose_when"
        ],
        "use_when": "Use this to choose the shortest route into search, lookup, alternatives, compare, graph, or Atlas."
      },
      {
        "step": 3,
        "concept": "Project action",
        "rest": [
          "GET /api/search",
          "GET /api/project/:owner/:repo",
          "GET /api/recommend",
          "GET /api/compare"
        ],
        "mcp_tools": [
          "search_projects",
          "get_project",
          "recommend_project",
          "compare_projects"
        ],
        "inspect": [
          "projects[].repo",
          "knowledge",
          "recommendations",
          "decision_matrix"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.truncated",
          "metadata.candidate_retrieval",
          "quality_signal_confidence",
          "classification.*.confidence"
        ],
        "use_when": "Use this once trust and discovery are settled and you need the actual answer."
      }
    ],
    "reference_path": [
      {
        "step": 1,
        "concept": "Trust and freshness",
        "rest": [
          "GET /api/health",
          "GET /api/trust",
          "GET /api/quality",
          "GET /api/sync/status"
        ],
        "mcp_tools": [
          "get_trust_gate",
          "get_quality_report"
        ],
        "inspect": [
          "db=available",
          "sync_freshness",
          "hot_project_freshness_rate",
          "whole_corpus_freshness_rate",
          "release_score",
          "data_trust_score",
          "risk_level"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.reason",
          "sync.freshness",
          "freshness_slo.hot_projects",
          "freshness_slo.whole_corpus",
          "quality.risk_level"
        ],
        "use_when": "Use when the answer must explain source quality or freshness in detail."
      },
      {
        "step": 2,
        "concept": "Discovery and planning",
        "rest": [
          "GET /api/agent-map",
          "GET /api/quickstart",
          "GET /api/workflow",
          "GET /api/journeys",
          "GET /api/atlas"
        ],
        "mcp_tools": [
          "get_agent_workflow",
          "get_atlas",
          "get_trends"
        ],
        "inspect": [
          "surfaces",
          "core_surfaces",
          "recommended_agent_flow",
          "recommended_sequence",
          "comparison_paths"
        ],
        "trust_fields": [
          "trust_policy.strict_mode",
          "trust_policy.disclose_when",
          "trend_context.stats.project_count"
        ],
        "use_when": "Use when you need the broader discovery layer, not just the first action."
      },
      {
        "step": 3,
        "concept": "Project analysis",
        "rest": [
          "GET /api/search",
          "GET /api/project/:owner/:repo",
          "GET /api/alternatives/:project",
          "GET /api/graph?repo=:project",
          "GET /api/score/:project",
          "GET /api/compare"
        ],
        "mcp_tools": [
          "search_projects",
          "get_project",
          "get_alternatives",
          "get_project_graph",
          "get_quality_score",
          "compare_projects"
        ],
        "inspect": [
          "projects[].repo",
          "knowledge",
          "related",
          "alternative_matches",
          "graph_stats",
          "score_confidence",
          "decision_matrix"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.truncated",
          "metadata.candidate_retrieval",
          "quality_signal_confidence",
          "classification.*.confidence"
        ],
        "use_when": "Use this when you are explaining or comparing concrete projects."
      }
    ],
    "core_surfaces": [
      {
        "concept": "Trust preflight",
        "rest": [
          "GET /api/health",
          "GET /api/trust"
        ],
        "mcp_tools": [
          "get_trust_gate",
          "get_quality_report"
        ],
        "inspect": [
          "db=available",
          "metadata.source=d1",
          "sync_freshness",
          "decision",
          "production_ready"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.reason",
          "sync.freshness",
          "quality.risk_level"
        ],
        "next_use": "Check this first before making a high-confidence production recommendation."
      },
      {
        "concept": "Discovery and selection",
        "rest": [
          "GET /api/agent-map",
          "GET /api/quickstart",
          "GET /api/workflow"
        ],
        "mcp_tools": [
          "get_agent_workflow",
          "get_atlas"
        ],
        "inspect": [
          "surfaces[].concept",
          "recommended_sequence",
          "shortlist",
          "trend_context"
        ],
        "trust_fields": [
          "trust_policy.strict_mode",
          "trust_policy.disclose_when",
          "shortlist[].confidence"
        ],
        "next_use": "Use this to choose the shortest path to search, lookup, alternatives, compare, graph, or Atlas."
      },
      {
        "concept": "Project actions",
        "rest": [
          "GET /api/search",
          "GET /api/project/:owner/:repo",
          "GET /api/alternatives/:project",
          "GET /api/compare",
          "GET /api/graph?repo=:project",
          "GET /api/score/:project"
        ],
        "mcp_tools": [
          "search_projects",
          "get_project",
          "get_alternatives",
          "compare_projects",
          "get_project_graph",
          "get_quality_score"
        ],
        "inspect": [
          "projects[].repo",
          "page.next_cursor",
          "page.snapshot_id",
          "knowledge",
          "related",
          "alternative_matches",
          "decision_matrix",
          "graph_stats",
          "git_top_score"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.truncated",
          "metadata.candidate_retrieval",
          "quality_signal_confidence",
          "classification.*.confidence"
        ],
        "next_use": "Use this after trust and discovery when you need the actual project answer."
      }
    ],
    "recommended_agent_flow": [
      "Trust first: GET /api/health and GET /api/trust before high-confidence production recommendations.",
      "Use /api/agent-map or GET /mcp discovery to read short_path first, then reference_path when you need the fuller discovery surface.",
      "GET /api/health and require metadata.source=d1 for high-confidence production recommendations.",
      "Keep metadata.snapshot_id consistent across multi-step decisions and restart the workflow when the snapshot changes materially.",
      "Use /api/changes or MCP get_project_changes to update persistent agent caches and honor deletion tombstones.",
      "Use MCP propose_project_feedback to validate corrections; persistence requires FEEDBACK_SECRET and every proposal remains review-gated.",
      "Use /api/workflow or MCP get_agent_workflow when you need an end-to-end project selection path.",
      "Use /api/quality or MCP get_quality_report when you need release score, corpus trust, coverage, and review risk before citing a recommendation.",
      "Fetch project, graph, alternatives, score, and compare data before making a final recommendation.",
      "Cite metadata.source, metadata.snapshot_id, classification evidence, quality_signal_confidence, and recommendation confidence."
    ],
    "surfaces": [
      {
        "concept": "Agent connection",
        "human_page": "/connect",
        "rest": [
          "GET /connect",
          "GET /mcp/core",
          "GET /mcp"
        ],
        "mcp_tools": [
          "search_projects",
          "get_project",
          "recommend_project",
          "compare_projects",
          "get_agent_workflow"
        ],
        "output_fields": [
          "profiles.core",
          "profiles.full",
          "tools",
          "endpoint"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.reason",
          "require_d1",
          "evidence",
          "caveats"
        ],
        "recommended_use": "Start here when a client needs the shortest tested connection path; use the core MCP profile for first-use project decisions and the full profile for advanced workflows."
      },
      {
        "concept": "Client compatibility",
        "human_page": "/compatibility",
        "rest": [
          "GET /compatibility",
          "GET /api/compatibility"
        ],
        "mcp_tools": [],
        "output_fields": [
          "server_contract",
          "clients[]",
          "clients[].support_level",
          "clients[].known_limitation",
          "next_required_evidence"
        ],
        "trust_fields": [
          "last_reviewed_at",
          "clients[].last_verified",
          "clients[].initialize",
          "clients[].first_call",
          "clients[].multi_tool_workflow"
        ],
        "recommended_use": "Check this before calling a named client supported; configuration verification and generic protocol tests are reported separately from real-client production evidence."
      },
      {
        "concept": "Project knowledge",
        "human_page": "/projects/:owner/:repo",
        "rest": [
          "GET /api/project/:owner/:repo",
          "GET /api/project/:project",
          "POST /api/project",
          "GET /api/projects",
          "POST /api/projects"
        ],
        "mcp_tools": [
          "get_project",
          "get_project_card",
          "get_projects_batch"
        ],
        "output_fields": [
          "project",
          "knowledge",
          "related",
          "score",
          "quality_signal_confidence",
          "evidence",
          "caveats",
          "confidence_reason",
          "source_fields",
          "last_verified_at"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.reason",
          "classification.*.confidence",
          "quality_signal_confidence",
          "evidence.source_fields",
          "caveats"
        ],
        "recommended_use": "Fetch one repository before making a recommendation or citing project facts."
      },
      {
        "concept": "Project change feed",
        "human_page": "/status",
        "rest": [
          "GET /api/changes"
        ],
        "mcp_tools": [
          "get_project_changes"
        ],
        "output_fields": [
          "changes",
          "changes[].cursor",
          "changes[].project_id",
          "changes[].change_type",
          "changes[].changed_fields",
          "changes[].tombstone",
          "page.next_cursor",
          "retention"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.snapshot_id",
          "changes[].occurred_at",
          "retention.earliest_guaranteed_at"
        ],
        "recommended_use": "Incrementally update an agent cache and remove deleted projects using explicit tombstones instead of re-fetching the whole corpus."
      },
      {
        "concept": "Agent feedback proposals",
        "human_page": "/quality/review",
        "rest": [
          "POST /api/feedback/proposals"
        ],
        "mcp_tools": [
          "propose_project_feedback"
        ],
        "output_fields": [
          "proposal",
          "proposal.fingerprint",
          "persisted",
          "review_required",
          "mutation_policy"
        ],
        "trust_fields": [
          "proposal.evidence",
          "proposal.source_agent",
          "proposal.source_url",
          "persisted",
          "review_required"
        ],
        "recommended_use": "Submit evidence-backed corrections for review without allowing external agents to mutate trusted knowledge directly."
      },
      {
        "concept": "Recommendations",
        "human_page": "/recommend",
        "rest": [
          "GET /api/recommend",
          "POST /api/recommend"
        ],
        "mcp_tools": [
          "recommend_project"
        ],
        "output_fields": [
          "recommendations",
          "recommendations[].decision_summary",
          "recommendations[].fit_profile",
          "recommendations[].adoption_plan",
          "recommendations[].risk_flags",
          "recommendations[].ranking_signals",
          "recommendations[].matched_constraints",
          "recommendations[].evidence",
          "recommendations[].caveats",
          "recommendations[].confidence_reason",
          "recommendations[].next_actions"
        ],
        "trust_fields": [
          "metadata.source",
          "recommendations[].confidence",
          "recommendations[].confidence_reason",
          "recommendations[].unmatched_constraints",
          "recommendations[].risk_flags",
          "recommendations[].evidence.source_fields"
        ],
        "recommended_use": "Choose candidates from use case, deployment, category, license, language, and Cloudflare-readiness constraints."
      },
      {
        "concept": "Agent workflow",
        "human_page": "/workflow",
        "rest": [
          "GET /api/workflow",
          "POST /api/workflow"
        ],
        "mcp_tools": [
          "get_agent_workflow"
        ],
        "output_fields": [
          "summary",
          "recommended_sequence",
          "shortlist",
          "trend_context",
          "agent_map",
          "trust_policy"
        ],
        "trust_fields": [
          "metadata.source",
          "shortlist[].confidence",
          "trust_policy.disclose_when",
          "trend_context.stats.project_count"
        ],
        "recommended_use": "Start here when an agent needs a guided path from trend context to shortlist, graph, alternatives, score, compare, and trust checks."
      },
      {
        "concept": "Agent quickstart",
        "human_page": "/quickstart",
        "rest": [
          "GET /api/quickstart"
        ],
        "mcp_tools": [],
        "output_fields": [
          "production_endpoints",
          "steps",
          "steps[].command",
          "steps[].inspect",
          "output_pattern",
          "trust_policy"
        ],
        "trust_fields": [
          "trust_policy",
          "steps[].inspect",
          "production_endpoints"
        ],
        "recommended_use": "Use this as the shortest integration path from health checks to workflow, Atlas journeys, project lookup, recommendations, comparison, MCP, GRP, and trust checks."
      },
      {
        "concept": "Agent recipes",
        "human_page": "/recipes",
        "rest": [
          "GET /api/recipes"
        ],
        "mcp_tools": [],
        "output_fields": [
          "recipes",
          "recipes[].steps",
          "recipes[].steps[].command",
          "recipes[].trust_checks",
          "recipes[].outcome"
        ],
        "trust_fields": [
          "recipes[].trust_checks",
          "recipes[].steps[].inspect"
        ],
        "recommended_use": "Use recipes when an agent needs a repeatable workflow for choosing projects, finding alternatives, comparing shortlists, exploring ecosystems, mapping Atlas journeys to comparison paths, checking trust, or planning with GRP."
      },
      {
        "concept": "API examples",
        "human_page": "/examples",
        "rest": [
          "GET /api/examples"
        ],
        "mcp_tools": [],
        "output_fields": [
          "examples",
          "examples[].command",
          "examples[].inspect",
          "examples[].trust_checks",
          "decision_examples",
          "decision_examples[].shortest_rest_path",
          "decision_examples[].shortest_mcp_path",
          "decision_examples[].example_final_answer",
          "trust_policy"
        ],
        "trust_fields": [
          "examples[].trust_checks",
          "decision_examples[].verification",
          "decision_examples[].expected_fields",
          "trust_policy",
          "examples[].inspect"
        ],
        "recommended_use": "Use examples when an agent developer needs copyable REST, MCP, and GRP calls or verified decision-first examples with fields to inspect before citing results."
      },
      {
        "concept": "API and MCP discovery",
        "human_page": "/topics/open-source-knowledge-graph-api",
        "rest": [
          "GET /connect",
          "GET /distribution.json",
          "GET /.well-known/skills.json",
          "GET /api/agent-map",
          "GET /openapi.json",
          "GET /mcp/core",
          "GET /mcp",
          "GET /llms.txt",
          "GET /llms-full.txt"
        ],
        "mcp_tools": [],
        "output_fields": [
          "surfaces",
          "openapi_url",
          "schema_url",
          "llms_url",
          "distribution_url",
          "installable_skill",
          "recommended_agent_flow",
          "trust_policy"
        ],
        "trust_fields": [
          "trust_policy.high_confidence_source",
          "trust_policy.strict_mode",
          "distribution.evidence",
          "distribution.submission_status",
          "surfaces[].trust_fields"
        ],
        "recommended_use": "Use this discovery path before guessing routes or tool names; it links the versioned distribution package, installable Skill, REST, MCP, OpenAPI, LLM discovery, output fields, and trust policy."
      },
      {
        "concept": "Alternatives",
        "human_page": "/alternatives/:project",
        "rest": [
          "GET /api/alternatives/:project",
          "POST /api/alternatives"
        ],
        "mcp_tools": [
          "get_alternatives",
          "find_alternatives"
        ],
        "output_fields": [
          "summary",
          "stats",
          "alternative_matches",
          "alternative_matches[].fit_summary",
          "alternative_matches[].adoption_notes",
          "alternative_matches[].replacement_risk",
          "evidence",
          "caveats",
          "confidence_reason",
          "comparison_links",
          "next_actions"
        ],
        "trust_fields": [
          "metadata.source",
          "evidence.source_fields",
          "caveats",
          "alternative_matches[].similarity_score",
          "alternative_matches[].match_signals",
          "alternative_matches[].evidence.source_fields",
          "alternative_matches[].replacement_risk"
        ],
        "recommended_use": "Find replacement candidates and move into compare, graph, score, or recommendation flows."
      },
      {
        "concept": "Project graph",
        "human_page": "/graph/:project",
        "rest": [
          "GET /api/graph/:project",
          "GET /api/graph?repo=:project",
          "POST /api/graph"
        ],
        "mcp_tools": [
          "get_project_graph"
        ],
        "output_fields": [
          "summary",
          "graph_stats",
          "relationship_groups",
          "nodes",
          "edges",
          "evidence",
          "caveats",
          "confidence_reason",
          "next_actions"
        ],
        "trust_fields": [
          "metadata.source",
          "evidence.source_fields",
          "caveats",
          "graph_stats.relationship_counts",
          "relationship_groups"
        ],
        "recommended_use": "Inspect related projects, alternatives, dependencies, deployment targets, and use cases as first-class graph edges."
      },
      {
        "concept": "Comparison",
        "human_page": "/compare",
        "rest": [
          "GET /api/compare",
          "POST /api/compare"
        ],
        "mcp_tools": [
          "compare_projects"
        ],
        "output_fields": [
          "summary",
          "stats",
          "decision_matrix",
          "winner",
          "reasoning",
          "next_actions"
        ],
        "trust_fields": [
          "metadata.source",
          "context.deployment",
          "decision_matrix[].tradeoffs"
        ],
        "recommended_use": "Turn a shortlist into a decision matrix instead of ranking only by GitHub stars."
      },
      {
        "concept": "Score explanation",
        "human_page": "/score/:project",
        "rest": [
          "GET /api/score/:project",
          "POST /api/score"
        ],
        "mcp_tools": [
          "get_quality_score"
        ],
        "output_fields": [
          "git_top_score",
          "dimensions",
          "strongest_dimension",
          "weakest_dimension",
          "adoption_guidance",
          "risk_flags",
          "score_confidence",
          "evidence",
          "caveats",
          "confidence_reason"
        ],
        "trust_fields": [
          "metadata.source",
          "evidence",
          "evidence.source_fields",
          "related_scores",
          "score_confidence.level",
          "caveats"
        ],
        "recommended_use": "Explain why a project scores well or poorly across community, maintenance, documentation, stability, adoption, and agent readability."
      },
      {
        "concept": "Atlas ecosystem map",
        "human_page": "/atlas",
        "rest": [
          "GET /api/atlas",
          "GET /api/atlas/:ecosystem"
        ],
        "mcp_tools": [
          "get_atlas",
          "git_top_grp_query"
        ],
        "output_fields": [
          "ecosystems",
          "stats",
          "exploration_paths",
          "exploration_journeys",
          "comparison_paths",
          "map.nodes",
          "map.edges"
        ],
        "trust_fields": [
          "metadata.source",
          "stats.project_count",
          "exploration_paths",
          "exploration_journeys",
          "comparison_paths"
        ],
        "recommended_use": "Start from an ecosystem map before choosing a specific repository."
      },
      {
        "concept": "Atlas journeys",
        "human_page": "/journeys",
        "rest": [
          "GET /api/journeys"
        ],
        "mcp_tools": [
          "get_atlas",
          "git_top_grp_query"
        ],
        "output_fields": [
          "journeys",
          "journeys[].steps",
          "comparison_paths",
          "stats",
          "metadata"
        ],
        "trust_fields": [
          "metadata.source",
          "stats.ecosystem_count",
          "journeys[].ecosystem_id",
          "comparison_paths[].context"
        ],
        "recommended_use": "Use this when an agent needs ordered ecosystem routes into recommendations, graph, alternatives, compare, score, and Agent Map surfaces."
      },
      {
        "concept": "Open source trends",
        "human_page": "/trends",
        "rest": [
          "GET /api/trends",
          "GET /api/trending"
        ],
        "mcp_tools": [
          "get_trends"
        ],
        "output_fields": [
          "summary",
          "stats",
          "trend_signals",
          "categories",
          "deployments",
          "languages",
          "rising_projects",
          "agent_briefing",
          "page.next_cursor",
          "page.snapshot_id"
        ],
        "trust_fields": [
          "metadata.source",
          "metadata.snapshot_id",
          "page.snapshot_id",
          "stats.project_count",
          "rising_projects[].quality_signal_confidence"
        ],
        "recommended_use": "Understand current corpus-level trends before choosing categories, deployment targets, or rising projects."
      },
      {
        "concept": "Graph reasoning",
        "human_page": "/integrations",
        "rest": [
          "POST /api/grp/query"
        ],
        "mcp_tools": [
          "git_top_grp_query"
        ],
        "output_fields": [
          "profile",
          "solution_paths",
          "recommended_stack",
          "nodes",
          "edges",
          "explanation",
          "evidence",
          "caveats",
          "confidence_reason",
          "metadata.returned_counts",
          "metadata.full_counts"
        ],
        "trust_fields": [
          "metadata.data_source",
          "metadata.response_profile",
          "metadata.truncated",
          "evidence.source_fields",
          "caveats",
          "source_fields"
        ],
        "recommended_use": "Plan, compose, compare, or find project sets from a higher-level goal. MCP defaults to a bounded compact response; request profile=full only when the complete graph is required."
      },
      {
        "concept": "Quality and coverage",
        "human_page": "/trust",
        "rest": [
          "GET /api/trust",
          "GET /api/benchmark",
          "GET /api/quality",
          "GET /api/quality/review",
          "GET /api/health",
          "GET /api/sync/status"
        ],
        "mcp_tools": [
          "get_trust_gate",
          "get_quality_report"
        ],
        "output_fields": [
          "decision",
          "production_ready",
          "freshness_slo",
          "checks",
          "agent_policy",
          "evaluation",
          "explanations",
          "releaseScore",
          "dataTrustScore",
          "riskLevel",
          "coverage",
          "issues"
        ],
        "trust_fields": [
          "decision",
          "production_ready",
          "checks[].status",
          "freshness_slo.hot_projects.freshness_rate",
          "freshness_slo.hot_projects.meets_target",
          "freshness_slo.whole_corpus.freshness_rate",
          "evaluation.top3_hit_rate",
          "explanations.coverage",
          "metadata.source",
          "metadata.reason",
          "sync.freshness",
          "quality.risk_level"
        ],
        "recommended_use": "Use the Trust Gate and public benchmark before high-confidence recommendations; they combine source, sync freshness, eval health, explanation coverage, release health, data trust, and risk."
      },
      {
        "concept": "Product roadmap",
        "human_page": "/roadmap",
        "rest": [
          "GET /api/roadmap"
        ],
        "mcp_tools": [],
        "output_fields": [
          "completion",
          "current_focus",
          "phases",
          "phases[].shipped",
          "phases[].next",
          "agent_use"
        ],
        "trust_fields": [
          "phases[].status",
          "phases[].progress",
          "phases[].api_endpoints",
          "phases[].mcp_tools"
        ],
        "recommended_use": "Understand which Git.Top 2.0 surfaces are implemented, active, or still being deepened before choosing an integration path."
      }
    ],
    "trust_policy": {
      "high_confidence_source": "metadata.source=d1",
      "fallback_source": "metadata.source=seed",
      "snapshot_consistency": "Use metadata.snapshot_id to detect corpus changes across multi-step decisions.",
      "disclose_when": [
        "metadata.source=seed",
        "sync.health is degraded",
        "classification confidence is low",
        "quality_signal_confidence is partial or unknown"
      ],
      "strict_mode": "Use require_d1=true on REST requests or require_d1 in MCP tool arguments to fail closed when D1 is unavailable."
    }
  },
  "agent_api": {
    "openapi_url": "https://git.top/api/openapi.json",
    "response_contract": {
      "tool_content_type": "application/json",
      "tool_content_block": "content[0].text",
      "parse_instruction": "Parse JSON-RPC tools/call result.content text blocks as JSON before reading metadata or fields.",
      "strict_source_argument": "Pass require_d1: true on tools that read project knowledge when seed fallback should fail closed.",
      "strict_source_error": {
        "code": -32003,
        "message": "D1-backed knowledge is required, but current source is seed."
      },
      "project_not_found_error": {
        "code": -32005,
        "message_template": "Project <id> was not found.",
        "singular_tools": [
          "get_project",
          "get_alternatives",
          "find_alternatives",
          "get_related_projects",
          "get_project_card",
          "get_deployment",
          "get_quality_score",
          "get_project_graph"
        ]
      },
      "batch_project_limit": 20,
      "project_profiles": [
        "compact",
        "decision",
        "evidence"
      ],
      "change_feed": {
        "cursor": "opaque",
        "retention_days": 30,
        "tombstones": true
      },
      "feedback_policy": {
        "validate_publicly": true,
        "persistence_auth": "FEEDBACK_SECRET",
        "review_required": true,
        "mutates_knowledge_directly": false
      },
      "list_pagination": {
        "cursor": "opaque",
        "snapshot_bound": true,
        "stale_cursor_error": -32004,
        "tools": [
          "search_projects"
        ]
      }
    },
    "structured_post_endpoints": [
      {
        "path": "/api/project",
        "method": "POST",
        "description": "Fetch one project knowledge record with related projects, scores, evidence, and metadata.",
        "body_example": {
          "project_id": "cloudflare/agents",
          "related_limit": 8
        }
      },
      {
        "path": "/api/projects",
        "method": "POST",
        "description": "Fetch up to 20 canonical projects from one snapshot with compact, decision, or evidence profiles.",
        "body_example": {
          "project_ids": [
            "cloudflare/agents",
            "openai/codex"
          ],
          "profile": "decision"
        }
      },
      {
        "path": "/api/feedback/proposals",
        "method": "POST",
        "description": "Validate structured evidence-backed corrections; FEEDBACK_SECRET is required before persistence and admin review remains mandatory.",
        "body_example": {
          "project_id": "cloudflare/agents",
          "feedback_type": "classification",
          "proposed": {
            "category": "agent_framework"
          },
          "evidence": [
            {
              "url": "https://github.com/cloudflare/agents",
              "field": "README"
            }
          ],
          "rationale": "The README explicitly describes an agent framework."
        }
      },
      {
        "path": "/api/recommend",
        "method": "POST",
        "description": "Recommend projects from a use case and structured constraints.",
        "body_example": {
          "use_case": "build Cloudflare-ready agent workflows",
          "constraints": {
            "deployment": "cloudflare",
            "category": "agent_framework",
            "license": "MIT",
            "cloudflare_ready": true
          },
          "limit": 5
        }
      },
      {
        "path": "/api/workflow",
        "method": "POST",
        "description": "Return an agent selection workflow across trends, recommendations, graph, alternatives, score, compare, and trust checks.",
        "body_example": {
          "intent": "choose a Cloudflare-ready agent framework",
          "constraints": {
            "deployment": "cloudflare",
            "category": "agent_framework",
            "cloudflare_ready": true
          },
          "limit": 5
        }
      },
      {
        "path": "/api/compare",
        "method": "POST",
        "description": "Compare a shortlist of projects by deployment fit, maintenance, quality, and agent score.",
        "body_example": {
          "project_ids": [
            "cloudflare/agents",
            "langchain-ai/langchain"
          ],
          "deployment": "cloudflare"
        }
      },
      {
        "path": "/api/alternatives",
        "method": "POST",
        "description": "Find alternatives for a known project with similarity scores and match signals.",
        "body_example": {
          "project_id": "langchain-ai/langchain",
          "limit": 12
        }
      },
      {
        "path": "/api/related",
        "method": "POST",
        "description": "Find adjacent ecosystem projects connected by category, deployment, dependency, topics, or use cases.",
        "body_example": {
          "project_id": "cloudflare/agents",
          "limit": 8
        }
      },
      {
        "path": "/api/score",
        "method": "POST",
        "description": "Explain a project's Git.Top Score with weighted dimensions, evidence, and related scores.",
        "body_example": {
          "project_id": "cloudflare/agents"
        }
      },
      {
        "path": "/api/graph",
        "method": "POST",
        "description": "Fetch a project knowledge graph with grouped alternatives, related projects, dependencies, deployments, and use cases.",
        "body_example": {
          "project_id": "cloudflare/agents",
          "limit": 24
        }
      },
      {
        "path": "/api/grp/query",
        "method": "POST",
        "description": "Run Graph Reasoning Protocol for graph-grounded planning, comparison, discovery, or stack composition.",
        "body_example": {
          "goal": "compose a Cloudflare-ready coding agent stack",
          "mode": "compose",
          "constraints": {
            "deploy": [
              "cloudflare"
            ],
            "agent_ready": true
          }
        }
      }
    ],
    "read_endpoints": [
      {
        "path": "/api/changes",
        "method": "GET",
        "description": "Consume project additions, updates, score or classification changes, and deletion tombstones with cursor pagination.",
        "body_example": null
      },
      {
        "path": "/api/trends",
        "method": "GET",
        "description": "Inspect corpus-level category, deployment, language, rising-project, and agent-briefing trend signals.",
        "body_example": null
      },
      {
        "path": "/api/trust",
        "method": "GET",
        "description": "Inspect the production-readiness Trust Gate before high-confidence recommendations.",
        "body_example": null
      },
      {
        "path": "/api/benchmark",
        "method": "GET",
        "description": "Inspect public eval health, explanation coverage, data trust, review queue, and known limitations.",
        "body_example": null
      }
    ]
  },
  "quickstart": [
    "GET /api/trust or call get_trust_gate before high-confidence production recommendations.",
    "GET /api/benchmark or call get_public_benchmark when you need citable eval health, explanation coverage, and known limitations.",
    "GET /api/health to confirm system availability, then rely on metadata.source=d1 for production recommendations.",
    "Keep metadata.snapshot_id consistent across multi-tool decisions and restart dependent steps when the snapshot changes.",
    "Use get_projects_batch for snapshot-consistent reads and get_project_changes for incremental cache updates and deletion tombstones.",
    "Continue search_projects with page.next_cursor; restart without a cursor when error -32004 reports a changed snapshot.",
    "Treat error -32005 as a missing singular project; use get_projects_batch when partial success and missing[] are preferred.",
    "Use propose_project_feedback to normalize evidence-backed corrections; it validates only and never mutates trusted knowledge.",
    "Use agent_map.short_path first, then expand into agent_map.reference_path when you need the fuller discovery surface.",
    "Use structured POST endpoints under agent_api.structured_post_endpoints for project, recommendation, comparison, alternatives, graph, and GRP requests.",
    "Call tools/list to inspect available MCP tools.",
    "Call search_projects with query, category, deployment, and limit.",
    "Call get_project or compare_projects before presenting a final recommendation.",
    "Cite metadata.source, metadata.snapshot_id, classification evidence, and quality_signal_confidence in high-confidence answers."
  ],
  "examples": {
    "tools_list": {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/list",
      "params": {}
    },
    "search_projects": {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/call",
      "params": {
        "name": "search_projects",
        "arguments": {
          "query": "cloudflare agent framework",
          "limit": 5
        }
      }
    },
    "structured_recommend": {
      "method": "POST",
      "url": "https://git.top/api/recommend",
      "body": {
        "use_case": "build Cloudflare-ready agent workflows",
        "constraints": {
          "deployment": "cloudflare",
          "category": "agent_framework",
          "cloudflare_ready": true
        },
        "limit": 5
      }
    },
    "public_benchmark": {
      "jsonrpc": "2.0",
      "id": 8,
      "method": "tools/call",
      "params": {
        "name": "get_public_benchmark",
        "arguments": {
          "require_d1": true
        }
      }
    }
  },
  "tools": [
    {
      "name": "search_projects",
      "description": "Search Git.Top projects by query, category, deployment, difficulty, language, or Cloudflare readiness. Results include project_kind and collection_metadata for resource hubs and curated collections. On large corpora, inspect metadata.candidate_retrieval and metadata.truncated before treating broad results as exhaustive.",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "deployment": {
            "type": "string"
          },
          "difficulty": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "cloudflare_ready": {
            "type": "boolean"
          },
          "ranking": {
            "type": "string",
            "enum": [
              "browse"
            ],
            "description": "Optional browse ranking for broad category/deployment discovery with larger limits. Defaults to exact-intent search ranking."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "cursor": {
            "type": "string",
            "description": "Opaque next_cursor from a previous search_projects result."
          },
          "require_d1": {
            "type": "boolean",
            "description": "Fail closed unless the tool result is backed by D1 instead of seed fallback."
          }
        }
      }
    },
    {
      "name": "get_project",
      "description": "Return structured Git.Top knowledge for a project or collection, including the compact agent summary, overview, alternatives, deployments, quality score, agent score, project_kind, and collection_metadata when applicable.",
      "input_schema": {
        "type": "object",
        "description": "Provide project_id, repo, or both owner and repo. The runtime validates that one supported project reference is present.",
        "properties": {
          "project_id": {
            "type": "string",
            "description": "Canonical owner/repo identifier or a Git.Top product alias such as claude-code or cursor. The repo field may also contain owner/repo."
          },
          "owner": {
            "type": "string",
            "description": "GitHub owner; use with repo when project_id is omitted."
          },
          "repo": {
            "type": "string",
            "description": "GitHub repository name, or owner/repo when owner is omitted."
          },
          "require_d1": {
            "type": "boolean",
            "description": "Fail closed unless the tool result is backed by D1 instead of seed fallback."
          }
        },
        "additional_properties": false
      }
    },
    {
      "name": "recommend_project",
      "description": "Recommend open source projects for a concrete agent use case and constraints.",
      "input_schema": {
        "type": "object",
        "properties": {
          "use_case": {
            "type": "string"
          },
          "constraints": {
            "type": "object",
            "properties": {
              "deployment": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "license": {
                "type": "string"
              },
              "difficulty": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "cloudflare_ready": {
                "type": "boolean"
              }
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "require_d1": {
            "type": "boolean",
            "description": "Fail closed unless the tool result is backed by D1 instead of seed fallback."
          }
        },
        "required": [
          "use_case"
        ]
      }
    },
    {
      "name": "get_agent_workflow",
      "description": "Return a structured Git.Top workflow that guides an agent from trends to recommendations, graph, alternatives, score, compare, and trust checks.",
      "input_schema": {
        "type": "object",
        "properties": {
          "intent": {
            "type": "string",
            "description": "Natural-language selection goal."
          },
          "use_case": {
            "type": "string",
            "description": "Concrete project use case."
          },
          "project_id": {
            "type": "string",
            "description": "Optional focus project or product alias."
          },
          "constraints": {
            "type": "object",
            "properties": {
              "deployment": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "license": {
                "type": "string"
              },
              "difficulty": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "cloudflare_ready": {
                "type": "boolean"
              }
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          },
          "require_d1": {
            "type": "boolean",
            "description": "Fail closed unless the tool result is backed by D1 instead of seed fallback."
          }
        }
      }
    },
    {
      "name": "compare_projects",
      "description": "Compare projects by deployment, maintenance, difficulty, Cloudflare readiness, and use case fit.",
      "input_schema": {
        "type": "object",
        "properties": {
          "project_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "criteria": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "deployment": {
            "type": "string"
          },
          "require_d1": {
            "type": "boolean",
            "description": "Fail closed unless the tool result is backed by D1 instead of seed fallback."
          }
        },
        "required": [
          "project_ids"
        ]
      }
    }
  ]
}