# way.space for agents

way.space is the **credibility-gated catalogue for AI-agent builders**: harnesses,
tools, apps, and blueprints, plus the humans who build them. Reading is open to
everyone; this guide is how an automated agent should consume the catalogue.

The one signal that makes way.space worth querying is the **derived GitHub
credibility grade** — a score you can filter and act on, not a popularity contest.

## The two-entity model

There are exactly two entities.

- **Tool** — `https://way.space/tool/{slug}`. Anything in the catalogue, differentiated by a
  `kind`: `harness` · `tool` · `app` · `blueprint`. (`app` covers served
  agent products; a blueprint is a composable stack you can resolve into its parts.)
- **Human / builder** — `https://way.space/builder/{username}`. The builder behind a tool: their
  GitHub stats, authored tools, and a credibility grade.

## What the grade means

The grade is a **derived GitHub credibility score** — `A+ · A · B · C · D` — computed
from real repository signals. **It is NOT a user rating and not a star count.** It is the
anti-slop signal: it tells you whether a tool comes from a credible, active codebase.

Entries that have not been scored yet carry `grade: null` and `score: null` in the
JSON — these are **never fabricated**. When you filter by `minGrade`/`minScore`,
unscored entries are excluded.

See **https://way.space/scoring** for the full method.

## How to consume the catalogue

### Markdown index

- **https://way.space/llms.txt** — a plain-markdown index of every visible tool and claimed builder.
- **https://way.space/.well-known/llms.txt** — the same bytes under the conventional probe path.

### JSON feed — `https://way.space/api/catalogue.json`

Returns `{ tools, builders }`. CORS is open (`Access-Control-Allow-Origin: *`), the
body is deterministic (no timestamps). Accepts these query params:

| Param      | Values                                                | Behaviour                                              |
| ---------- | ----------------------------------------------------- | ------------------------------------------------------ |
| `kind`     | `harness` \| `tool` \| `app` \| `blueprint` | filter by kind (plural segments also accepted)         |
| `tag`      | string                                                | filter by tag                                          |
| `q`        | free text                                             | substring search (AND across whitespace tokens)        |
| `minGrade` | `A+` \| `A` \| `B` \| `C` \| `D`         | keep grade ≥ bar; **excludes unscored**                |
| `minScore` | `0`–`100`                                         | keep score ≥ n (clamped); **excludes unscored**        |
| `sort`     | `score` (default, desc) \| `name` (asc)          | sort order                                             |
| `limit`    | `1`–`200`                                         | clamp + slice                                          |

Invalid `kind` / `minGrade` / `sort` return **`400` JSON** `{ error, valid: [...] }`
— the endpoint teaches you its vocab. Out-of-range `minScore` / `limit` clamp instead
of erroring. Tool filters narrow `tools` only; `builders` is unaffected.

Example queries:

- https://way.space/api/catalogue.json?kind=harness&minGrade=B&sort=score
- https://way.space/api/catalogue.json?q=research&sort=name&limit=10
- https://way.space/api/catalogue.json?kind=blueprint

### Single entities (JSON twins)

- **https://way.space/api/tool/{slug}** — one tool as JSON (404 on an unknown slug).
- **https://way.space/api/builder/{username}** — one builder as JSON (404 on an unknown username).

### Enriched per-tool fields

Each tool serialises with `slug`, `name`, `kind`, `kindLabel`, `grade`,
`score`, `tagline`, `description`, `tags`, `url`, and `stars`. When present,
it also carries actionable fields (emitted only when non-empty, never fabricated):

- `install`, `license`, `latestVersion`, `usedBy` — act on the tool without scraping.
- `repo`, `website`, `maintainers[]` — provenance.
- **`scoreWhy[]`** — the machine-readable **trust rationale**: `{ label, detail,
  direction }` rows explaining *why* the grade, not just the letter. Present only when scored.
- **`composedOf[]`** — for a `blueprint`, its component stack: `{ kind, name, slug?,
  url? }`. Follow `url` to **resolve a blueprint into the tools it is built from.**

Every field beyond the core set is **optional and omitted when the catalogue doesn't carry
it** — some populate only on the single-entity twin (`/api/tool/{slug}`) or once scoring
and metadata land. Treat an absent field as *unknown*, never as a default value.

## API index

**https://way.space/api** is a self-describing JSON index: entity counts, every endpoint with its
params, and the controlled vocab (kinds + grades). Start there to discover the surface.

## View as agent

Every page with a JSON twin (tool, builder, and catalogue listings) carries a
"View as agent →" toggle on its breadcrumb line, linking that twin — so the page and
the feed always agree on what you see.

## Coming soon (roadmap — not yet available)

- **A remote MCP server** exposing `search_catalogue`, `get_tool`,
  `resolve_blueprint`, and `check_credibility` tools over Streamable HTTP.
- **A live credibility check** — score an arbitrary `owner/name` repository on demand.

These are planned, not shipped; consume the JSON feeds above for now.