Repo Aeo

repo-aeo — Repo Discoverability Kit (RDK)

English | Русский

Make any repository, npm package and docs site findable and recommendable for humans, AI agents and search engines.

RDK scores how discoverable your repository is, fixes the parts that can be fixed automatically, and keeps it from regressing in CI. It is the tool you point at a repo that is good but invisible.

The audit runs 44 checks in under 300 ms offline on this repository (measured with rdk audit --format json, duration_ms field) and carries 0 runtime dependencies, so npx stays fast and the supply chain stays small.

Quickstart

Prerequisites: Node.js >= 18

# 1. add RDK to your repository
npm install --save-dev repo-aeo

# 2. scaffold the config and the missing files
npx repo-aeo init --apply

# 3. see the score and the prioritised fix list
npx repo-aeo audit

# 4. run the test suite
npm test

Two-minute setup for a repository you do not own yet: clone it, run npx repo-aeo init --apply, then npx repo-aeo audit. Everything the CLI writes is a reviewable diff — it never publishes, tags or force-pushes. The one exception lives in CI: the opt-in autofix job force-pushes its own dated rdk/autofix-<date> bot branch and opens a reviewable PR.

Ways to use it

You fork nothing and install nothing permanently. Pick the surface that matches how you work — each pulls the engine on demand:

Commit to it and exactly two files ever appear in your repository: the workflow above and .discoverability/project.yml, the generated source of truth for your metadata. The two RDK repositories (engine and the action wrapper) stay ours — they are the factory, not a dependency you carry.

The problem

You shipped a good package, but nobody finds it: npm search buries it, AI assistants recommend the incumbents, and the README explains the philosophy for 90 lines before the first runnable example.

Fixing that once is the easy half. The hard half is keeping it fixed: six months later a contributor's PR "tidies up" the README with a banner and a table of contents, the quickstart sinks below line 60, the tests stay green — and the package quietly disappears from search results and AI answers again. Nobody notices, because nothing in CI watches discoverability.

RDK makes it a tested property: audit locally, gate in CI on every pull request.

Who is it for

• Maintainers publishing an npm package for the first time.
• Teams whose library is good but invisible in AI answers, npm search and GitHub search.
• Agent-tooling authors who want their repo to be usable by coding agents out of the box.
• Researchers and OSS projects that need citation and discovery metadata.

What you get

Three layers, because a one-off script is not enough:

Commands

npx repo-aeo init          # create .discoverability/project.yml + minimal safe files
npx repo-aeo audit         # score 0-100 + findings (json | markdown | github-comment)
npx repo-aeo fix           # preview safe autofixes; --apply to write them
npx repo-aeo npm-surface   # package.json publish surface + npm pack --dry-run
npx repo-aeo github-sync   # push description/homepage/topics (needs --apply --ack --reason --plan-digest)
npx repo-aeo channels      # list every distribution channel, applicability and next action (read-only)
npx repo-aeo submit        # submit to a distribution channel: --channel <id> (needs --apply --ack --reason --plan-digest)
npx repo-aeo track         # campaign dashboard: live status, adopt existing PRs, sync the ledger
npx repo-aeo skill install # link the agent skill into OpenCode/Claude/Codex skill dirs

npx repo-aeo-mcp serve # the same engine as an MCP server: 9 read-mostly tools
claude mcp add rdk -- npx repo-aeo-mcp serve
docker run -i repo-aeo-mcp serve

Every write operation requires an explicit flag. audit is read-only and works offline; --online adds link checks and live GitHub metadata.

Examples

1. Score a repository

$ npx repo-aeo audit            # measured on fixtures/demo-repo, offline
score: 52/100 (grade F) · checks: 20/43 passed · findings: 10 error, 13 warn, 10 info (19 autofixable) · mode: offline (use --online for link + GitHub checks)

2. Fix what is safe to fix

$ npx repo-aeo fix --dry-run     # review the diff
$ npx repo-aeo fix --apply       # 16 files: README sections, AGENTS.md draft, llms.txt, CITATION.cff, ...

3. Check the publish surface

$ npx repo-aeo npm-surface --pack
| exports | conditions: import, require; subpaths: . |
⚠️ present in the repo but not in the tarball: llms.txt

4. Keep it from regressing in CI

# .github/workflows/rdk.yml — in YOUR repository
- uses: actions/checkout@v4
- uses: WhiteBite/rdk-discoverability@v1
  with:
    min_score: ${{ vars.RDK_MIN_SCORE || 0 }}

GitHub downloads the action, the action pulls the engine from npm — nothing to install or fork. This is the same action this repository's own CI runs.

The CLI itself never force-pushes; the workflow's opt-in autofix job (gated by safety.allow_autofix) force-pushes only its own dated rdk/autofix-<date> bot branch and opens a PR for review.

5. Monitor it continuously

$ npx repo-aeo-mcp score
Discoverability score: 100/100 (grade A)
checks passed: 44/44 - errors 0 - warnings 0 - autofixable 0
trend: no history yet

The first run records the score; every subsequent run prints the delta instead (for example trend: 90 -> 96 (up)).

6. Teach an agent to do it

skills/repo-discoverability/SKILL.md → description triggers on
"make repo discoverable", "add topics", "improve README for users and agents",
"prepare npm metadata", "generate AGENTS.md", "optimize for AI search",
"run a distribution campaign", "submit to awesome lists"

Use cases

• Score a repository's discoverability and get a prioritised fix list.
• Generate and maintain AGENTS.md, llms.txt and llms-full.txt for a repo.
• Prepare package.json metadata, exports and tarball contents before an npm release.
• Fill GitHub description, homepage and 8–20 topics from one config file.
• Keep discoverability from regressing with a weekly GitHub Action audit.
• Run a distribution campaign: prepare entries for the relevant curated lists, submit reviewable PRs, track them in .discoverability/submissions.json.
• Watch score, npm search score and GitHub signals from an MCP client or a cron job.

Discoverability Score

Six weighted axes, renormalised over the axes that apply to your project:

Grades: A ≥ 90 · B ≥ 80 · C ≥ 70 · D ≥ 55 · F below. Full model: docs/scoring.md.

Why choose this

• One config file drives everything. .discoverability/project.yml feeds the README, AGENTS.md, llms.txt, npm metadata and GitHub topics — no drift between them.
• Same audit locally and in CI. Ships as a CLI, an agent skill and a GitHub Action, so a human and an agent run identical checks.
• Audit-only by default. Writes need an explicit flag; publish/tag/release are out of scope entirely and require a human ACK string.
• Deterministic generators. Zero runtime dependencies, no LLM in the loop: every generated line is traceable to the config or to a file in the repo.

How RDK compares

Most tools in this space anchor to a served website (llms.txt validators, GEO graders, Lighthouse), a published package (npms.io) or a docs build (framework generators). RDK anchors to the git working tree: it audits and repairs the repository itself, before anything is served or published.

Direct comparables: repo-local artifact graders and generators

Adjacent territory: sites, indexes and agent context

Orthogonal by design: Scorecard grades how safe a repo is to consume, community standards grade human onboarding, packers serialize content, DeepWiki hosts a generated wiki and CHAOSS measures community behaviour over time. None of them repairs the repository; RDK does not replace any of them.

Where RDK is deliberately narrower

• No codebase packing. Repomix and ai-digest ship the repo as one context file; RDK points agents at the right files (llms.txt, AGENTS.md) instead of serializing content.
• No CFF schema validation. RDK generates a CITATION.cff stub; validating it against the versioned schema is cffconvert's job, and the community's fix story there is reject-in-CI, never rewrite.
• One root llms.txt pair. No per-path or per-section corpora like Ray's sectioned llms-full.txt files or Cloudflare's per-product variants.
• Repo-local llms.txt checks. "Does the served site match the file" is only an MCP tool and an --online probe, not a full served-vs-file diff like llms-txt-check.
• npms.io is fetched, not computed. If npms.io goes away, the npm axis falls back to registry metadata only.
• The ack string is a reusable constant. A determined model can type it; single-use, argument-bound tokens (as in mature write-gated MCP servers) close that loop tighter. Preview-by-default and the reason audit log are the compensating controls here.
• The rubric is heuristic, not observational. A 96/100 means the repo satisfies the checks, not that it outranks anything in a population-wide model like npms.io's.
• No activity or adoption axis. repo-health-radar and CHAOSS grade maintainer responsiveness, release cadence and contributor diversity from event history; RDK scores artifacts only, so a well-documented dead repo scores high here.
• No visibility-in-engines measurement. Searchstack probes Google, AI Overviews and chat assistants about your brand; RDK can only make the repo legible, never observe how engines actually rank it.
• Location-awareness of trust files is GitHub's job. The community profile accepts CODE_OF_CONDUCT in .github/, root or docs/; RDK's checks look at fixed paths.

What llms.txt provably buys

Consumed on demand by agents: the spec states the file is "used on demand, when an agent needs information about a topic while assisting a user", for inference rather than training. OpenClaw ships llms.txt discovery as default agent behavior since 2026-02; Chrome's Lighthouse Agentic Browsing scores sites on it; Cloudflare, Mintlify, GitBook, Wix and Yoast publish or generate it as the ecosystem convention, and tools like mcpdoc feed it to IDE agents.

What it does not buy: none of GPTBot, ClaudeBot, PerplexityBot, Google-Extended or Bingbot documents fetching /llms.txt during training or indexing crawls — their official bot pages contain no mention of it. The defensible value is inference-time agents, repo-reading tooling and the discoverability audits above, not crawler traffic.

Where RDK leads

• The only tool above whose unit of analysis is the working tree: everything is fixable before the first deploy or publish. The nearest twin, repo-health-radar, shares the shape (zero-dep CLI, marketplace action, min-score gate) but grades human-maintainer axes and ships no autofixes, MCP server or agent artifacts.
• README primitives are scored for agent consumption (install-command detectability, quickstart placement, parseable structure); the numeric README graders that exist reward human presentation instead.
• Cross-source coherence (config vs package.json vs GitHub vs README) has no analog; topic managers are write-only wrappers.
• Double-run idempotency (rdk fix twice produces no diff) is a tested gate, where codemod ecosystems treat it as folklore.
• A write-guarded MCP tool with reason logging and tool annotations on every tool, in a zero-runtime-dependency package that audits fully offline.

Status

Actively developed. v0.1 ships the CLI, the skill, the Action and the MCP server. IDE packaging is next (roadmap issues).

Repository map

License

MIT — see LICENSE. Citation metadata: CITATION.cff.