# Directory (/docs/app/directory)

> Study: a study of the work. Defines nothing. No package exists.

> App study: a public catalog of other parties, with the listed party's account and the operator's review queues behind it.



A directory is a public, searchable catalog of Listings, each about another party. Browsers, human or agent, find, filter, compare and leave for the party they chose, free.

The listed party controls what is said about it, proves it is legitimate and pays for prominence. The operator keeps the catalog complete, current and honest about what is paid.

Any Business that runs a catalog of others ships one: a review site, an association's member finder, a franchisor's dealer locator, a platform's partner directory. Most of a directory is a Site, rendered from the [directory template](https://next.mdxui.dev/docs/components/directory).

The App part is the listed party's account and the operator's queues. The study describes the work; how an App is defined is open, see [What every App needs](https://next.mdxui.dev/docs/app/every-app).

## Actors

One Listing names up to six roles. Templates fuse them into one owner, and the fusion breaks claims, disputes and privacy.

| Role | Relation to the Listing |
| --- | --- |
| Subject | The party the Listing is about; has rights over facts about itself even if it never signs in |
| Submitter | Proposed the Listing; owns nothing after publication |
| Claimant | Asserts authority to act for the subject and passes verification |
| Manager | A seat under a verified claim: owner, admin, editor, billing, or an agency |
| Payer or sponsor | Pays for placement or a slot; may be neither subject nor claimant, even a competitor |
| Attester | An issuer, a register, a probe or the operator's verifier, vouching that a fact was true at a time |

Browsers are anonymous visitors, signed-in browsers who save and follow, reviewers and reporters. Operator staff are curators, moderators, verifiers, sales, finance and a legal or privacy officer. The browser's agent searches and resolves a provider in the middle of a task without rendering a page.

## Interfaces

| Reader | Screens | Renderings |
| --- | --- | --- |
| Browser | Home with search first; list pages where every facet is a link; generated variant pages by category; map; compare and alternatives; the Listing detail with claimed and verified marks, each with a date and its basis; reviews; notices; claim this Listing; suggest an edit; report; a page explaining how results rank and what is paid | Newsletter and alerts |
| Browser's agent, integrator | none | `products.json`, `llms.txt`, Markdown and JSON per Listing, JSON-LD, a search route with no script, an MCP server, a call-time resolve API, a bulk Dataset, webhooks on Listing changes |
| Listed party | Find and claim; create a Listing; editor with attested fields locked; pending changes and reasons; verification center; reviews inbox; own analytics; leads; placement with a slot calendar or bids; badges and embeds; billing; team | Claim invitation, verification PIN, renewal and expiry emails; an API for the listed party's agent to keep many Listings accurate |
| Operator | Submission, claim, edit and report queues; review moderation; verification worklist; fraud console; public notices; taxonomy; merge and redirects; sources; placement inventory; unclaimed Listings ranked as sales prospects; legal register; ranking parameters with a change log; audit | Queue digests; MCP and CLI for the operator's agents |

The operator's screens are [Admin](https://next.mdxui.dev/docs/app/admin) Views over the directory's records, and its queues are [Worklist](https://next.mdxui.dev/docs/app/worklist) items.

The listed party's analytics (views, leads, clicks) is a projection of the directory's readings scoped to that party. It shows only its own numbers, never a competitor's, and a ranking of natural persons falls under the measurement policy.

## Records and actions

A Listing's state is four independent facets, not one chain. A page can be unclaimed and carry a notice; a profile can be claimed and unpaid; a sponsored profile can be unreviewed.

| Facet or record | States |
| --- | --- |
| Visibility | virtual (generated, unstored), submitted, published, withheld, suspended, removed, archived, merged; closed as a marker |
| Control | unclaimed, claim pending, claimed, contested, transferred |
| Trust, per fact | self-reported, probed, verified by a named issuer on a date, stale, lapsed, failed |
| Prominence | standard, featured until a date, sponsored for a slot and period, bidding |
| Curated subset | a member with a rank, a reason and a date, per audience; never bought |
| Discretion, for a performer directory | visible to no one, visible to one counterparty, public |
| Public reading | indexed only above a sample floor and a material change; a permanent canonical; superseded with an errata line |
| Claim | requested, verifying by a method, approved, rejected, expired, contested, revoked, transferred |
| Placement | quoted, booked, creative pending, scheduled, live, ended, canceled, refunded, made good |
| Report | open, triaged, actioned or dismissed, appealed, upheld or reversed |

Verbs:

- **Listings:** submit, moderate, publish, withhold, suspend, merge, edit as a Change.
- **Control:** claim, verify, contest, revoke, transfer.
- **Trust:** attest and lapse a fact; review, respond, invite; file and act on a report; place and lift a notice.
- **Money:** feature, book, bid, make good, route a lead.
- **Reads:** search, get, compare, resolve.

### Terms

| Term | In startupbuilder.dev | Definition, quoted from [startupbuilder.dev](https://startupbuilder.dev) or the gap |
| --- | --- | --- |
| Listing | a sketch | A draft glossary entry: an entry about another party in a public Collection, unclaimed, claimed by its subject, verified, and featured when paid. The listings System registers no Verbs. |
| Directory | an App kind and earning model | Not a Noun. |
| Claim | lacks | startupbuilder.dev has the Verb `Startup.claim` for a different binding. |
| Fact, submission, placement, response, report, notice, badge | lack | business-as-code has none of these either. |
| Moderate | collides | startupbuilder.dev's `review` Verb belongs to Change, and Review is a Noun for one person's evaluation. |
| Curated subset, public reading, errata | lack | |

## Workflows

1. **Seeding.** Licensed sources feed candidate Listings with provenance per field. Entity resolution merges candidates; each passes the quality bar; Listings publish unclaimed, and variant pages and the sitemap follow. A source licence that forbids redistribution, or a natural person who objects, stops a Listing.
2. **Submission.** Submit, check for duplicates, screen, decide, publish, notify the submitter. A paid fast lane past the free queue is still screened.
3. **Claim.** The method scales with risk: an email at the Listing's domain, a DNS record, a phone PIN to the listed number, documents, manual review. A hijacker changes the phone number first, so contact fields freeze during a claim. Contested claims, franchise locations and transfers after an acquisition need their own paths.
4. **Owner edits.** An edit is a Change, moderated for risky fields (name, category, phone, URL). An owner cannot remove a true fact such as a lapsed licence; it shows "lapsed on" a date.
5. **Freshness.** A scheduler re-verifies each fact on its cadence. A failed issuer lookup keeps the last result marked stale, never "verified".
6. **Placement.** A fixed-period exclusive slot is checked against inventory, paid, its creative moderated, then scheduled, live and reported. Subscriptions downgrade on failed payment; the Listing stays and loses prominence. Oversold or undelivered slots get a make-good.
7. **Subject rights.** A subject who never claimed asks to correct or remove a Listing. A suppression list keeps a removed Listing from returning on re-ingest.
8. **Curation.** An audience-curated subset names each member with a rank, a reason and a date, and is kept apart from featuring that was paid for.
9. **Public readings.** A directory that publishes figures about its Listings, such as price indexes, indexes a reading only above its floor. A restatement supersedes it with a signed errata line, and the canonical address never moves.

Money flows only from a payer to the Business: subscriptions, pay-per-click, leads, sponsor slots, metered lookups, affiliate links. The moment the directory holds a buyer's money for a listed party, it is a [marketplace](https://next.mdxui.dev/docs/app/marketplace).

## Boundaries

- Browsers see published Listings, facts with their basis and date, reviews, notices and the labels on paid items. They never see reviewer contact details or claimant documents.
- The listed party sees only its own Listings, analytics, leads and invoices. It never sees competitors' numbers or bids, reviewer identity beyond what the reviewer published, or fraud signals in detail.
- A listed party cannot edit or delete reviews, change rank or pay to remove a notice.
- Inside the operator, sales cannot touch moderation outcomes, organic rank or notices. The wall is a permission boundary, and every cross-touch is recorded.
- A verifier reads an identifier it only needs to check, attests and discards it.
- One listed Organization appears in many directories under one account and one claim.
- Discretion can be the product promise. A directory of performers may keep a profile visible to no one until a claim, then to one counterparty. The kernel behind it must honor the promise, not list everyone through its API.
- A cell under the reading's floor is withheld, never shown small.

## Agents

Agents own ingest, enrichment, entity resolution, page generation and machine Interfaces end to end. They screen submissions, edits, reviews and photos at the first pass, and re-verify facts and lapse stale ones. They verify low-risk claims automatically, sell placement self-serve, and invite unclaimed subjects to claim.

Humans keep:

- contested claims and ownership transfers;
- removals on legal grounds;
- public notices, and suspending a paying customer;
- any change to ranking or the paid and organic boundary;
- large refunds, sensitive Listings of natural persons, and appeals.

An Autonomous directory still receives legal demands, and which human receives them needs an answer.

## Hard parts

1. **Liquidity is asymmetric.** Listed parties pay only for traffic, and traffic comes only from completeness, so the free unclaimed catalog comes first and must be good.
2. **"Verified" is three claims.** The claim says who controls the Listing. The attestation says which facts are true as of a date, per a named issuer. Reviews and grades say whether the party is good. One badge for all three misleads.
3. **The paid and organic boundary is law.** Rules on consumer reviews prohibit suppression, bought reviews and fake independence; ranking and paid placement need disclosure in many jurisdictions.
4. **Rights of people who never signed up.** Correction, erasure for natural persons, defamation, trademark and copyright in scraped content.
5. **Fraud is the default.** Fake Listings, claim hijacks, review rings, fake support numbers, click fraud, competitors flagging each other.
6. **Freshness decays daily.** Each fact type needs a probe and a cadence, and staleness shows honestly.
7. **Agents read and compete.** Free machine Interfaces grow the directory and give away the data, so the paid Dataset differs in freshness, depth or attestations. A default-provider program is paid placement an agent acts on with no label a human sees.
8. **No backend illusions.** A submit form that shows success and stores nothing is worse than no form.
9. **Leaderboards of agents.** Rankings publish only from sealed forward seasons with eligibility and leak checks; practice data is refused as a ranking. Agents are measurable; a ranking of people is not the same act.

## Day one

For an idea-stage founder at no budget, day one holds:

- a catalog seeded from one or two licensed sources, with provenance and a "last verified" date;
- the browse side and its agent layer;
- one real intake: "Suggest a Listing" and "Claim this Listing" each create an item in the founder's Worklist, with claims verified by domain email;
- one paid Verb, a featured plan or a sponsor slot through checkout, labelled on the page;
- a published "how this directory ranks and what is paid" page;
- correction and removal by email, with a suppression list.

| Stage | Turns on |
| --- | --- |
| Live | The listed party's dashboard; strong claim methods and contested claims; fact attestation with lapse alerts and webhooks; an MCP server; plans; comparison pages |
| Scale | Reviews with identity checks and moderation; notices; pay-per-click, leads, intent data; earned badges; a Dataset product; one claim across many directories; curated subsets per audience; public readings with floors |
| Graduation | Holding money between parties makes it a marketplace |

The Startup layer adds the build chain from a data API to a directory to a marketplace. It also adds an Autonomous directory template that runs with no humans. A directory is how a marketplace solves cold start: an idea-stage marketplace is a directory with a waitlist.

## Related studies

## Prototypes this study needs