The explorer's sorts (#7753)
/explore, GET /api/v1/explore, the MCP tool explore and the terminal's search line (/, then a line with kind: or sort:) are one action, explore in src/actions/explore.ts. The line is kind:app sort:likes updated:7d owner:name archived:yes forks:3 ships:1 live:yes words.
sort: takes one of:
| sort | ranks by |
|---|---|
score (default) | the front page's score: forks, ships, use and freshness at the admin's weights, plus a modest lift for likes |
forks | public forks by people |
ships | pulls merged in the last 30 days |
likes | likes on posts about the app |
use | hours awake in the last 30 days |
fresh | the last merge |
new | the most recently made app first (a person by their newest app) |
name | A to Z |
The page's tabs are Best, Forks, Shipped, Liked, Use, Fresh and Newest; a row shows N likes when N > 0, on the web and in the terminal.
Why a row ranks where it does (#11296)
Each row's meta line starts with one phrase for the signal that most explains its place: 12 forks, 3 shipped this month, 2 likes, shipped today, in use. On a named sort it is that sort's signal; on score it is the largest term of the score, weighed as the ranking weighs them (frontScore at the forge's front weights, and LIKE_WEIGHT for likes; a tie goes to forks, ships, likes, freshness, use). whyOf in actions/explore.ts reads it from the row's numbers, with no query. The number the phrase says is left out of the rest of the line, so nothing is said twice. The terminal's explorer lines (/ then kind: or sort:) show the same phrase first and drop the same duplicate. A row with nothing to say has no phrase; sort:name and sort:new have none.
The figures line on an app row (#13483)
An app's meta line opens with its numbers in full: 3 forks, 5 ships, 2 likes, shipped 2d ago · description. Forks and ships are always said, even at zero; likes appear when there are some, or when the sort is likes; sort:use adds N h in use. So the figure the active sort ranks by is always on the line. The age is shipped <time> on the page (the exact date is the <time> element's title), never shipped when there is none. The meta stays one ellipsised line at 360 px (.row-meta, asserted in test/explorer-why.test.ts). GET /api/v1/explore and the MCP explore tool carry the same line as figures on each app row (the age worded by shippedWords: shipped 2 days ago), figuresOf in actions/explore.ts; the terminal's explorer rows say it too. People and forges have no figures; they keep the why phrase. Each app row also carries forks, ships, likes and updatedAt (the last ship, null when none) at the top level, copied from the same numbers and shippedAt the line is made of, by rowsWithWhy for both doors (test/explore-api-numbers.test.ts).
How likes count
A like is a feed_like row (one per person and post, src/feed/likes.ts). An app's count is the likes on posts about its repository, read only for repositories the viewer may read: a private app's likes are never in a public row, and a stranger never sees the private app at all. A person's count is the sum over the apps shown to the viewer.
In score, likes add 0.5 × ln(1 + likes), small next to forks (3) and ships (2). The weight is a constant in explore.ts, not one of the front page's admin weights.
An unknown sort: word is a 400 naming the sorts above (see the end of this page).
When an unknown kind:, sort:, updated: or archived: value is within edit distance 2 of a known one (and nearer than the value is long, so one or two characters of junk suggest nothing), the note ends with Did you mean <a>sort:forks</a>?, a link to the same view with that word mended (in the parameter form below, /explore?sort=forks). Only the first such word is mended per line; a word repeated is mended everywhere. GET /api/v1/explore and the MCP explore tool carry the same as suggest ("garden sort:forks", the whole corrected line), absent when there is none. The terminal shows it as plain text under "Read as:". It is a pure function of the line: nothing is looked up.
One word on every surface (#10387)
What a person filters on /explore an agent filters with the same words. Each filter is its own parameter: the page's chips are plain links like /explore?kind=app&sort=forks (the default view is bare /explore, and only the free words stay in q), so a filtered view is a link that reloads the same (#10727). The API takes the same parameters, and the MCP tool the same names as arguments.
| the page offers | the parameter | API GET /api/v1/explore | MCP explore |
|---|---|---|---|
| Best / Forks / Shipped / Liked / Use / Fresh / Newest | sort=score forks ships likes use fresh new (name by hand) | ?sort=forks | { sort: "forks" } |
| All / Apps / People / Forges (admin) | kind=app person forge | ?kind=app | { kind: "app" } |
| Any time / Today / This week / This month | since=1d 7d 30d (updated= is the same) | ?since=7d | { since: "7d" } |
| Show archived | archived=yes | ?archived=yes | { archived: "yes" } |
| (owner link on a row) | owner=name | ?owner=name | { owner: "name" } |
| (type it) at least N forks by people | forks=3 (0–1000) | ?forks=3 | { forks: "3" } |
| (type it) at least N merges in 30 days | ships=1 (0–1000) | ?ships=1 | { ships: "1" } |
| (type it) awake in the last 30 days | live=yes (no is no filter) | ?live=yes | { live: "yes" } |
| Mine (signed in, beside the kind tabs) | mine=yes (no is no filter) | ?mine=yes | { mine: "yes" } |
| the search box | q=words | ?q=words | { q: "words" } |
The one line still works everywhere: ?q=kind:app sort:forks garden and { q: "kind:app sort:forks garden" } read the same as the separate parameters, and old /explore?q=… links keep working. When a parameter and the same key in q are both given, the parameter wins (?q=sort:name&sort=forks sorts by forks). A parameter's value is one word; one the explorer does not take is an unknown word like any typed in q, and is refused the same way (below). The terminal's search line takes only the line. It takes forks:N, ships:N and live:yes there too (screens/dashboard.ts reads the line with readExploreLine): forks:1 live:no leaves the rows the page leaves, and forks:abc or live:maybe is named under Read as: as forks:abc is not a count, live:maybe is not an answer.
The three return the same ordered rows (test/explore-parity.test.ts; the URL form in test/explore-url.test.ts).
A forks: or ships: value that is not a whole number from 0 to 1000 (abc, -1, 1.5, 1001) and a live: that is not yes or no are unknown words like any other: 400 naming the word. Spawned forges carry no numbers, so any of the three leaves them out. The page's filter chips, Drop links and Clear filters carry the three words.
An unknown filter word is refused the same way everywhere: 400 from the API ({ "error": "unknown_filter", "message": "sort:bogus is not a sort — use score, forks, …", "suggest"? }), an unknown_filter error from the MCP tool, and 400 on the page, which still draws the note, the did-you-mean link and the results. This replaces the earlier note-only answer (#7595).
Mine (#13161)
mine=yes (or mine:yes in a line) keeps the viewer's own apps and the viewer's own person row: the owner is the viewer's name. Signed out it matches nothing, never everyone. Filters live in the URL, so /explore?kind=app&mine=yes&sort=fresh reloads and sends as the same view, and equals choosing Apps, Mine and Fresh by hand, row for row (test/explore-url-filters.test.ts). The terminal's search line takes mine:yes the same way (mine:yes after /): a guest sees no rows, the signed-in viewer sees their own (test/tui-dashboard-explore.test.ts). A mine: value other than yes or no is an unknown word like the others.
Paging (#11376)
A list holds 60 rows a page. When there are more, /explore ends with Previous and Next links around "Page N of M", plain links that keep kind, sort, since, owner, archived and the words and add page=N (page 1 has no page). ?page=2 is server-rendered and works without JavaScript. The page links say rel="prev" and rel="next". An old ?cursor= link shows the first page with one line saying the link is out of date. A page that is junk, zero or negative shows the first page, and one past the end shows the last, never an error. GET /api/v1/explore returns next_cursor and takes ?cursor=, and the MCP explore tool takes and returns the same cursor.
The terminal's explore lines page the same way: when the answer carries next_cursor the list ends with one line, more results — n, and n fetches the next page and appends it; the last page shows no line. The cursor is kept with the line it came from, so changing the line starts again at the first page. A cursor the forge refuses shows the first page with one plain line (that page is no longer there — showing the first page), never an error screen. A fetch that fails (not a refusal) keeps the pages already shown and says could not fetch more results — n to retry. The line takes the list's last row, so it shows on any terminal tall enough for a list.
Make it yours on an app row
An app's row carries action: { do: "make_it_yours", label: "Make it yours" } exactly when copyable is true (MAKE_IT_YOURS in actions/explore.ts).
label is the page button's text and do is the name of the MCP tool that forks; it plans unless called with dryRun: false.
As a feed (#10967)
GET /explore.atom is /explore as an Atom feed, public, for a feed reader. It holds the apps /explore ranks first for a stranger (default ranking, apps only, read through the page's own explore), at most 30 (EXPLORE_ENTRIES in web/feeds.ts), shown newest-made first, one entry each titled with the app's name, linked to its page (rel="alternate") with its description as the summary. Private and archived apps are never in it. It is cached for five minutes (cache-control: public, max-age=300) and carries a weak ETag, so a reader that sends If-None-Match gets a 304. /explore links it with <link rel="alternate" type="application/atom+xml">. Server-Timing names read and render.
The terminal's palette has Explore feed, which opens or shows the feed's address (copy it into a reader).
The count and the way back (#11323)
Under the filters, /explore says how much a filter leaves: 66 results, 2 apps, 1 app, 0 results, in the words of exploreCount in src/actions/explore.ts (the count is the whole filtered list, not the page). While a filter narrows the list (kind, words, archived, updated or owner; the sort only orders) the line ends with Clear filters, a link to bare /explore. When nothing matches the line reads 0 results with that one Clear filters link (terminal and MCP say the same words); the chips above it still take one filter off, and the empty state only names the filters. With no filter and nothing public the line is silent; the empty state speaks.
In the terminal the same sentence sits in the Read as: line under the search box (Read as: kind:app · 2 apps · Esc clears); Esc clears the line.
What a row shows
A row shows the app's name, what it does in plain words, and the one signal that explains its place (the other numbers are left off the page; the API and the MCP still carry them all). The filter line is the search box, the kind tabs and, signed in, "Mine"; "Sort and time" opens the sorts, the time windows and "Show archived", and stays open while one of them is set. The ranking order is unchanged.
The terminal's explore screen deliberately keeps the stacked numbers (forks, ships, likes, use) that the page leaves off: a terminal row has the width for them and no second tap to reach them. The ranking is the same on both.