<!--
metadata:
  wiki: agentkit-seo
  module: agentkit-seo-github
  title: "GitHub runtime knowledge"
  status: stable
  confidence: likely
  last_reviewed: 2026-05-27
  review_by: 2026-08-27
  source_status: mixed
  agent_priority: high
-->

# GitHub runtime knowledge

> This file contains durable GitHub knowledge for agents. Use it to keep profile, repository, search, Linguist, and agent-readiness advice factual and source-aware.

## 1. Load contract

Read this file only after [index.md](index.md) indicates that the current task needs compiled GitHub knowledge.

If this file is unavailable in an older install, continue with `references/profile-and-repo-structure.md`, `references/search-indexing-and-linguist.md`, `references/profile-and-repo-audit.md`, `references/copilot-and-agent-readiness.md`, or `references/section-recipes.md` as appropriate. Mark search, Linguist, and agent-readiness guidance as lower confidence if the wiki is unavailable.

## 2. Evidence labels

Use the AgentKit SEO evidence labels defined in `agentkit-seo/wiki/agentkit-seo.md`.

For GitHub work, `Verified` means the fact was observed in public GitHub profile fields, repository metadata, topics, README content, fetched files, language stats, or local repository files. `Inaccessible` commonly applies to private repositories, account settings, social-preview settings, contribution visibility settings, organization-only material, and analytics.

## 3. Canonical definitions

**GitHub discoverability** means making a profile or repository easier to find, understand, evaluate, and trust through native GitHub fields, readable files, public metadata, and coherent project packaging.

**Showcase repository** means a public repository selected to represent the user's target role, stack, maturity, and proof of work.

**Profile README** means the special repository README rendered on a user's profile page. It should add context, not replace profile fields, pinned repositories, or repository documentation.

**Linguist integrity** means the repository language stats represent the real first-party code mix without hiding genuine source files or mislabeling generated, vendored, documentation, or data files.

**Agent-readiness** means making repository instructions, setup, validation, architecture, and contribution constraints clear enough for coding agents and human maintainers to operate safely.

## 4. Platform constraints

- `stable`: A GitHub bio is short and should act as a compact role summary, not a full profile.
- `stable`: Repository names, About text, topics, README openings, and pinned selection should describe the same project positioning.
- `stable`: Public code search depends on repository visibility and default-branch content. Private material is not public recruiter evidence.
- `stable`: Archived repositories are poor anchors when searchability or active maintenance matters.
- `stable`: GitHub language statistics are generated by Linguist and can be affected by generated, vendored, documentation, or data-heavy files.
- `stable`: `.github/copilot-instructions.md` is the repo-wide Copilot instruction path, and `.github/instructions/*.instructions.md` is the path-specific instruction pattern.
- `stable`: `AGENTS.md` files use scoped instructions where nearest applicable files matter for agent behavior.
- `likely`: Four to six curated pinned repositories usually communicate stronger proof than a scattered or stale pin set.
- `likely`: A custom social-preview image is useful for showcase repositories when the image clearly represents the project.
- `inferred`: README quickstarts and evaluation paths are stronger trust signals for reviewers than decorative badges alone.
- `disputed`: Stars, forks, activity timing, or contribution heatmaps should not be presented as deterministic ranking levers.

## 5. Search and Linguist rules

- `stable`: Inspect file roles before recommending `.gitattributes` changes.
- `stable`: Use Linguist overrides to correct representation, not to hide real first-party source.
- `stable`: Do not mark first-party source as vendored to manipulate the language bar.
- `likely`: Large generated files, notebooks, data dumps, vendored dependencies, and documentation can distort language stats.
- `likely`: Untouched forks are usually weaker portfolio anchors than owned, documented, active repositories.
- `inferred`: Clear file names, symbols, directory names, and README terms improve human and tool comprehension, even when ranking effects are not known.

## 6. Agent failure modes

- Claiming exact GitHub ranking, Explore, or code-search mechanics without documented evidence.
- Treating stars, forks, contribution graphs, or activity cadence as guaranteed discovery levers.
- Recommending `.gitattributes` patches from the profile page without inspecting repository files.
- Hiding real source files with broad vendored/generated rules to change language stats.
- Inventing repository maturity, security status, vulnerability impact, CI health, license status, or pinned status.
- Rewriting technical work into inflated marketing language unsupported by README or code evidence.
- Suggesting `AGENTS.md` or Copilot instruction files for simple repositories before fixing README, About text, topics, and pins.
- Loading every repository for a bounded profile audit instead of following the depth contract.

## 7. Output rules

When producing a GitHub audit or implementation plan:

- State which profile, repository pages, README files, topics, language stats, and local files were inspected.
- Separate profile, pinned repository, repository metadata, searchability, Linguist, and agent-readiness issues.
- Use `Evidence`, `Why it matters`, and `Change` for high-priority findings.
- Label `.gitattributes` recommendations as verified only after inspecting file roles.
- Prefer concrete README, About text, topic, pin, or file changes over generic branding advice.
- Include a one-line `Depth note` when the audit did not inspect every relevant repository or file.

Shared taxonomy: [agentkit-seo/wiki/agentkit-seo.md](../../agentkit-seo/wiki/agentkit-seo.md). Source grounding: [hub/github/sources.md](../../../../hub/github/sources.md).
