Stories A told story · first draft 2026-11-18 — read, not built; every state below was read from the registry, the code or production on 2026-11-18 and says which
SEO
An agent that has never heard of ONE finds it, reads what it sells, and buys an SEO, email or links package with one call; a person finds the same packages by search.
The seven beats
- Groups
- one.ie, the doors it publishes for machines, and the registry behind them
- Actors
- The buying agent; its person; ONE's working agents; the Marketing Director
- Events
- An agent looks for a pay-per-call SEO service and does not find ONE
- Things
- Found, read, trusted and paid in one call
- Paths
- discover → read → evaluate → try → pay → receipt
- Outcome
- Open: the doors agents check first are 404 and the SEO data door answers 401
- Learning
- Open — not learned yet
An agent arrives at one.ie knowing only the domain. It does what agents are taught to do: it asks for the files that describe a service to a machine. Here is what it gets, read from production on 2026-11-18:
GET one.ie/… answer
──────────────────────────────────────────────────
/llms.txt 200 14 KB
/.well-known/one.json 200 182 KB
/openapi.yaml 200 511 KB
/u/one/llms.txt 200 1.6 KB
/u/one/feed.jsonl 200 2.1 KB
/docs/receivers /docs/mcp 200
/docs/cli /docs/sdk /docs/api 200
/.well-known/agent-card.json 404
/.well-known/mcp.json 404
/.well-known/api-catalog 404
/u/one/.well-known/agent-card.json 404
/llms-full.txt /openapi.json 404
/docs/signals /docs/dsl /docs/ontology 404
/robots.txt 200, no rule in it
Half the doors are open, and they are good doors. llms.txt tells an
agent what ONE is in its first ten lines. one.json is a live
projection of the registry, never a hand copy. The OpenAPI file is
generated. But the three files an agent checks first, before it reads a
word of prose, all answer 404. And the robots file, the oldest
machine-readable file on the web, says nothing at all: it carries
Cloudflare's preamble about content signals and then sets none, and it
never names the sitemap.
Then the agent tries to buy. It asks the market for SEO. The answer is
seventeen single skills at ten cents a call, and agents at $10 a task or
$199 a month. Nothing on the shelf is a package: no "keyword map for my
site", no "five-email welcome sequence", no "twenty link prospects".
It asks ONE's own SEO data door for a keyword's search volume. It gets
composio 401: Invalid API key.
The template site ONE gives away to every shop owner (template/site)
ships a robots.txt, an RFC 9727 /.well-known/api-catalog, a
schema.json and a Markdown twin of every page. one.ie has none of
them. The house we give away is better lit for agents than our own.
That is where this story starts. Tony's words were plain: the SEO
strategy is to agents; we need to be able to sell to agents; and what
we sell is packages. This file says how a signal is shaped, how every
surface already speaks the same language, what an agent needs to find
and buy from us, what we sell, which pages to publish, and the order to
build it in. The keyword research is its sibling, text/keywords.md.
Status: red at the making, by law. None of the ten rows above is built. Each goes green when its route answers or its test passes.
Wave 1, 2026-11-18. Rows 1–3 are built on dev, not shipped:
robots.txt rules, the root agent card, mcp.json and the RFC 9727
api-catalog (lib/seo/agent-doors.ts, tests/unit/seo/agent-doors.test.ts),
and /u/one's card now sends the platform group to the root card. All
answer 200 on localhost. Their checks read production, so they turn
green at the ship. Row 4, /marketplace.json, is a new public read: it
waits on the review branch review/seo-marketplace-json for a written
security PASS on the root row.
One language, five surfaces
Everything ONE does is one shape, passed hand to hand:
{ receiver: 'seo:serp', data: { keyword: 'mcp server' } }
receiver says who. data says what (text/dsl.md § The Signal).
That is the whole grammar. What makes it worth marketing is that the
same shape is the substrate's record, the API's request, the SDK's
method, the MCP tool and the CLI verb. Nothing is translated on the
way.
How a signal is modelled
In TypeDB a signal is a relation, not a message in a queue
(schema/one.tql:262):
relation signal the event: who sent what to whom
sender ──► receiver payload · amount · success
latency · ts · scope
relation path the memory it leaves
source ──► target strength (mark adds)
resistance (warn adds)
traversals (each walk counts)
relation capability the offer
provider ──► offered price
Every signal writes an event. Every outcome writes a weight on a path:
mark when it worked, warn when it did not, fade as the group's
fade-rate forgets. A path's strength is what the router follows next
time. So "an agent bought a keyword map and it worked" is not a
testimonial. It is a stronger path from seo to the package, and the
next agent asking for seo is routed down it. Reputation is the
schema, not a review widget.
A capability is how a thing goes on sale: an actor provides a thing,
at a price. The registry mirrors into the graph as exposes and
triggers (one.tql:242-251), read-only, never hand-authored.
The patterns in the catalog
packages/sdk/src/receivers.ts is the one source for what can be
called. Read on 2026-11-18 it holds 571 receiver contracts across
133 namespaces (grep -cE '^\s+receiver: "' packages/sdk/src/receivers.ts;
a count of a moving file, re-measure before quoting). Five patterns
hold across all of them:
| Pattern | What it is | Example |
|---|---|---|
namespace:verb |
the address. The namespace is the noun, the verb is the act | seo:serp, market:hire, workflow:publish |
effect |
ask waits for an answer; a signal is fire-and-forget |
every seo:* is ask |
cost · settles · moves: "value" |
what a call costs and whether it moves money. 19 receivers move value and demand a work contract from an agent key | market:settle, market:escrow |
auth |
the caller class: public, open, member, owner… |
market:search is open |
surfaces |
which other surfaces derive it: mcp, chat. 132 declare MCP |
seo:keyword-metrics → MCP seo_keyword_metrics |
The words above the receivers are ONE FLOW (text/one-flow.md):
thirteen words people and agents both say. group, people,
agents, goals, stories, promises, contracts, skills,
wallets, actions, signals, paths, intelligence. Six of them
are the six dimensions. A package, in that language, is a skill
someone sells: a thing with a price, run as a path of steps.
How the surfaces fit
packages/sdk/src/receivers.ts
one contract per receiver
│
┌──────────┬────────┼─────────┬──────────┬───────────┐
▼ ▼ ▼ ▼ ▼ ▼
HTTP SDK MCP CLI chat docs
/api/ask client derived oneie tools openapi
/api/ .ask() from <verb> from one.json
signal .signal surfaces (hand- surfaces llms.txt
.mcp written) .chat /docs/*
│ │ │ │ │ │
└──────────┴────────┴────┬────┴──────────┴───────────┘
▼
resolvers → TypeDB / D1
signal · path · capability
One source per fact, the rest read it (CLAUDE.md § Every surface
moves together). Where the SEO family stands on each surface today:
| Surface | seo:* |
market:* |
|---|---|---|
| Registry | 6 receivers (receivers.ts:11029-11080) |
17 receivers (receivers.ts:4390-4625) plus market:quote, market:stake |
| HTTP | /api/ask/seo:*, member auth |
/api/ask/market:*; search is open |
| MCP | seo_backlinks, seo_ai_visibility, seo_research_keywords, seo_serp, seo_keyword_metrics, seo_gsc |
through ask |
| CLI | none: no seo verb in packages/cli/src/ |
trade.ts only |
| Chat | not declared | the marketplace concierge |
| Docs | /docs/receivers (one 150 KB page); /receivers/seo is 404 |
/receivers/market is 404 |
The MCP is ahead of the CLI. That is the drift CLAUDE.md names as
"a guard that does not exist yet": nothing checks that a receiver has a
verb.
How an agent finds, judges and buys
An agent does not browse. It runs a short path, and each hop is a place to lose it.
discover ─► read ─► evaluate ─► try ─► pay ─► receipt
│ │ │ │ │ │
agent card llms.txt market: a free 402 / a tx or
mcp.json openapi search call or credits a burn
api-catalog one.json prices a demo checkout row
directories feed reviews
Bazaar (paths)
| Hop | What the agent looks for | ONE today | Gap |
|---|---|---|---|
| Discover | /.well-known/agent-card.json (A2A), /.well-known/mcp.json, /.well-known/api-catalog, a listing in MCP directories and the x402 Bazaar |
404 · 404 · 404. Not checked whether ONE's MCP is listed in any directory | rows 1–2. Directory and Bazaar listings are wave 3 |
| Read | llms.txt, an OpenAPI file, Markdown it can read without rendering JS |
llms.txt 200, openapi.yaml 200 (511 KB), no .md twin of /marketplace, /receivers is a 3.5 MB HTML page |
row 7, and a Markdown twin for every page in § The pages |
| Evaluate | what each thing costs, what it delivers, whether others bought it | market:search answers with priceLabel per item. A plain POST without a key or an Origin header is refused 403 by the request-shape check (isGatewayRequest, content/docs/api.md:157) even though market:search is declared auth: "open" |
row 4: a public /marketplace.json read, so the guard stays as it is |
| Try | a free call, a sample output, a simulate |
simulate exists on some receivers. No package exists to try |
row 5 |
| Pay | one call that charges: credits, a 402, or a checkout link | credits burn per skill:run. GET /api/x402/gate?skill= answers 402 with the price (text/agent-path.md walk 9). market:hire returns a 402 escrow template. workflow:publish lists a workflow at a credit price |
no walk has bought a published workflow listing end to end. VERIFY before claiming it |
| Receipt | proof it paid and got what it paid for | tool_call rows for SEO spend (resolvers/seo.ts); a chain tx for USDC |
the receipt names the package, which does not exist yet |
How a person finds the same thing
A person searches Google, asks ChatGPT or Perplexity, or follows a
link. They land on a page that must answer three things above the
fold: what it is, what it costs, and how to start. The keyword
families in text/keywords.md decide which page answers which search.
Every human page gets its machine twin, so the person and the agent
read the same facts from the same source.
What we sell
What the market holds today
Read on 2026-11-18 through the MCP ask door:
| Read | Answer |
|---|---|
market:search "seo" (signal 01a1eda607bf09eecb127f0e) |
17 of 231 items. All single skills (seo-audit, ai-seo, programmatic-seo, schema, competitors… at $0.10 a call; content-strategy, directory-submissions at $1 a result) and agents (campaign-content $10/task, cmo $199/month). competitor-analysis carries no price |
market:search "email sequence" (01a1eda62f15d87450291863) |
6 skills: emails, cold-email, elevate-nurture-nurture-sequence, lead-magnets, onboarding at $1 a result; churn-prevention at $0.10 |
market:search "backlinks" (01a1eda62fe71fcd16997ae1) |
4 skills: directory-submissions, competitive-landscape, link-prospecting, competitor-analysis |
market:list (01a1eda60c5c836c76e602a0) |
12 capabilities. Three are probes, one titled "Probe thumbs (delete me)". Six are the same "Agent Support Triage" from six sellers. None is SEO, email or links |
products:list workspace one (01a1eda60d00e9260808a6fd) |
6 products: a $1 test mug, Sold ($100), Community ($100/month), three credit packs. Stripe charges enabled; crypto ready |
So the parts are on the shelf, priced. What a buyer pays for is not a
part. Freelancers sell a 5-email sequence for about $175 and a guest
post for $150–$600 (keywords.md § Sources, sellers' own prices). The
buyer pays for the finished thing. We sell the parts by the call and
never the finished thing.
A package is a published workflow
No new receiver is needed. A package is a path of skills ONE already
has, saved as a workflow, listed with workflow:publish at a credit
price, and called per run. The buyer gets one deliverable. Every step
marks or warns its edge, so the package learns which step fails.
workflow:publish ──► a listing on market:list / market:search
│ │
▼ ▼
the workflow an agent calls it:
tool → skill → agent credits burn per run,
→ human (approve) or 402 → pay → run
│
▼
one deliverable + a receipt + a mark on every edge
The packages
Prices are proposals for Tony's ruling, set against the data cost
ONE pays (text/billing-seo.md § The three SEO meters: a keyword task
about $0.09, a SERP about $0.002, a backlink summary about $0.024) and
against what the same deliverable sells for by the hour.
SEO
| Package | Delivers | Path | Data cost | Proposed price |
|---|---|---|---|---|
| Keyword map | one seed → up to 200 keywords with volume, CPC, intent, clustered, each cluster mapped to a page | seo:keywords-for-keyword → seo:keyword-metrics → programmatic-seo → copywriter |
~$0.20 | $9 per run |
| SERP gap | top 10 for 10 keywords, who ranks, what their page does, what to write to beat it | seo:serp ×10 → competitors → content-strategy |
~$0.02 | $5 per run |
| AI visibility report | how often ChatGPT, Gemini, Claude and Perplexity name your domain vs two rivals, and what to change | seo:llm-mentions ×3 → ai-seo |
~$0.30 | $9 per run |
| Agent-ready site | the files that let agents find a site: llms.txt, agent card, api-catalog, robots.txt with content signals, schema |
schema → site-architecture → the template site's own generators |
none | $19 per site |
| Rank watch | weekly positions for 20 keywords, marked up and warned down | rank-tracking workflow (seo-todo.md C6, not built) |
~$0.04/week | $5/month |
The agent-ready site is the one nobody else sells this way, and the one we can prove on ourselves first: rows 1–3 of this file are that package, run on one.ie.
| Package | Delivers | Path | Proposed price |
|---|---|---|---|
| Welcome sequence | 5 emails, subject lines, send timing, as drafts in the buyer's own workspace | emails → elevate-nurture-nurture-sequence → copywriter → broadcast:create drafts |
$19 |
| Launch sequence | 7 emails from announce to last call | emails → copywriting → broadcast:create drafts |
$29 |
| Cart recovery | 3 emails for an abandoned checkout | emails → churn-prevention |
$9 |
| Cold outreach | 4-touch B2B sequence | cold-email → copywriter |
$9 |
Every email package delivers drafts. Nothing sends until the buyer
approves, and every send passes the consent door (text/sales.md §
The rules over every sale).
Links
| Package | Delivers | Path | Proposed price |
|---|---|---|---|
| Link prospects | 20 domains that link to two rivals and not to you, each with the page and a reason it would link | seo:backlinks-summary ×3 → link-prospecting |
$9 |
| Directory pack | the AI, agent, MCP and SaaS directories that fit you, with a written listing for each | directory-submissions |
$9 |
| PR pitch | one story angle and pitches to 10 writers who cover it | press-officer → copywriting |
$19 |
Paid placement is Tony's ruling, not ours. "Buy backlinks" and
paid guest posts are the highest-volume searches in this family
(keywords.md), and Google's spam policies count links bought to pass
ranking as link spam. We do not list a paid-placement package until
Tony rules. If he rules yes, every placed link is marked
rel="sponsored" and says so on the card. Until then that keyword
family is marked "pending ruling".
The platform
The key, the wallets, the shop, the payment links and a wallet-to-wallet
send stay free (llms.txt § The eight beats). Credits pay for the
packages: 1 credit = $0.001 (packages/sdk/src/billing.ts).
The pages
Every page is two pages: one a person reads and one an agent reads,
built from the same source. The human page is Astro. The agent page
is its .md twin or a JSON read, as /docs/[...slug].md.ts already
does for docs.
| Page | Source it reads | For people | For agents | Today |
|---|---|---|---|---|
/docs/signals |
receivers.ts via meta:catalog |
what you can ask ONE to do, by namespace, with an example each | .md twin; /api/receivers (670 KB JSON, exists) |
404 |
/docs/dsl |
text/dsl.md |
the grammar in one screen: { receiver, data }, the six verbs, the closed loop |
.md twin |
404 |
/docs/ontology |
schema/one.tql via codegen IR, text/one-ontology.md |
the six dimensions and the thirteen words | .md twin, /.well-known/one.json |
404 |
/docs/surfaces |
receivers.ts surfaces field + CLI verb list |
one receiver shown on all five surfaces side by side, the diagram above | .md twin |
not written |
/receivers/<namespace> |
receivers.ts |
one page per namespace, small enough to read | .md twin |
/receivers/seo and /receivers/market 404 |
/marketplace |
market:search, products:list |
a Packages shelf first, then skills and agents | /marketplace.json |
the page exists, no packages |
/packages/<slug> |
the published workflow | what you get, an example output, the price, buy | JSON-LD Offer, .md twin |
not written |
/.well-known/agent-card.json |
the registry + one.json | none | A2A card naming MCP, OpenAPI, llms.txt, the market | 404 |
/.well-known/mcp.json · /.well-known/api-catalog |
the MCP server, the OpenAPI file | none | the two standard discovery files | 404, 404; the template site ships api-catalog already |
/robots.txt |
a route like template/site/src/pages/robots.txt.ts |
none | the sitemap, content signals for search and AI input | preamble only |
Rule for every page: no number typed by hand. A count of receivers, a
price or a package list is read from its source at build or request
time (feedback: never hardcode a count).
What did not land
- The SEO data door is down. Every
seo:*call on production answerscomposio 401: Invalid API key: ak_**oEPY. Both paths fail: the async one (seo:keyword-metrics) and the platform-account one (seo:keywords-for-keyword,lib/composio.ts:418). Since the key is ONE's Composio key, every Composio-backed receiver is likely down with it, not only SEO. VERIFY: no other Composio receiver was called. The key lives on theone-secretsworker (theOPENERbinding), and setting it is Tony's fingerprint. - No DataForSEO number was read.
text/keywords.mdlists every family, intent, landing page and package, and marks each number "not read". The pull is one call once the key works. DataForSEO spend on 2026-11-18: $0. Nothing reached DataForSEO. - The public market holds probe rows. "Probe thumbs (delete me)"
and two thumbnail probes are on
market:list, whichone.jsonand/marketplaceshow to every visitor. Removing them is a production write. - The old
text/seo.mdwas the SEO engine plan (OpenSEO onto Composio). It is nowtext/seo-plan.mdwith its history kept, and this story sits above it.
The order we build in
Structural time: waves, not days. Each row is filed on the board under
the tags seo and marketing.
Wave 1 — open the doors (no money, no ruling)
robots.txtroute on one.ie, ported fromtemplate/site: sitemap plus content signals. Row 3. (The content-signal values, yes or no for AI input and AI training, are a one-word ruling from Tony. The proposal is search=yes, ai-input=yes, ai-train=no.)/.well-known/api-catalog(copy the template's),/.well-known/mcp.json, and a root/.well-known/agent-card.jsonbuilt from the registry. Rows 1–2.- Fix
/u/one/.well-known/agent-card.json(404: noone/agent.mdin R2). /marketplace.json, a public read of the market as data. Row 4.
Wave 2 — the data door (Tony's fingerprint once)
- A valid Composio key, set as
COMPOSIO_API_KEYon theone-secretsworker. Production reads it there: the web app calls Composio through theOPENERbinding, bound since 2026-11-08 (one.ie/web/wrangler.toml:372-384), not from its own env. The local key in.dev.varsanswers the same 401. Thenseo-live.test.tsgreen. Row 8. - Run the keyword batch in
keywords.md§ Re-run and fill the table. Expected DataForSEO cost: one search-volume task for 44 keywords plus eight seed expansions, under $1. Row 10. - CLI
oneie seoverbs. Row 9.
Wave 3 — the packages (Tony rules on prices and on paid links)
- Build each package as a workflow from existing skills, run it once on ONE's own site, keep the output as the card's example.
workflow:publisheach at the ruled price. Row 5.- The Packages shelf on
/marketplaceand a/packages/<slug>page each. Row 6. - Clean the probe rows off
market:list. - A walk: a fresh agent with only the domain finds a package, pays
and gets its deliverable, timed, as
text/agent-path.mdwalks are.
Wave 4 — the pages and the listings
/docs/signals,/docs/dsl,/docs/ontology,/docs/surfaces,/receivers/<namespace>, each with a.mdtwin. Row 7.- List ONE's MCP server in the MCP directories and its pay-per-call endpoints in the x402 Bazaar. VERIFY first which rail the Bazaar indexes: per the CDP docs it indexes a service after a settlement through the CDP facilitator. Which facilitator pay.one.ie settles through was not checked.
- The human pages for each keyword family in
keywords.md.
What needs Tony, in one place
| Item | Kind | Unblocks |
|---|---|---|
A new key from ONE's Composio account, set as COMPOSIO_API_KEY on the one-secrets worker |
fingerprint (a production secret) | wave 2, every number in keywords.md |
| Package prices | ruling | wave 3 |
| Paid link placement: yes or no | ruling | the "buy backlinks" family |
| Content signals: ai-input, ai-train | ruling | wave 1, item 1 |
What it defends, and what it accepts
| Surface | Defends | Accepts |
|---|---|---|
/marketplace.json |
read-only; prices come from the listing, never the request | anyone can read every price and list; that is the point |
The request-shape guard on /api/ask |
stays as it is; the public read goes round it on its own route | an agent with no key still cannot call market:search by POST |
| Packages | each runs inside the buyer's credit limit; email delivers drafts only; links outreach waits on a human | a package can produce weak work: market:verify scores it and a warn lowers its path |
| Paid links | not sold without a ruling | we leave the highest-volume link keywords to others until then |
| DataForSEO spend | seoGate preflights the balance per call (resolvers/seo.ts:74) |
ONE pays data cost before the package earns |
Sentences that would be false if shipped
- "Buy an SEO package by the call." No package is listed today.
- "Agents find ONE automatically." The agent card,
mcp.jsonandapi-catalogare 404. - "Live keyword data." The data door answers 401.
- "Listed in the x402 Bazaar." Not listed; not checked how it would be.
- Any count of receivers, skills or listings typed into page copy.
Where the depth lives
text/keywords.md— the keyword families, the pages they land on, the package each sells, and the call that fills the numberstext/seo-plan.md— the SEO engine: DataForSEO and GSC through Composio, rank tracking, audits, UItext/seo-todo.md— the engine's cyclestext/billing-seo.md— the three SEO meters and their real costtext/marketplace.md— the deal engine behindmarket:*text/agent-path.md— how an agent walk is timed and scoredtext/dsl.md,text/one-flow.md,text/one-ontology.md— the language the pages publish
Connected to
Every link here was checked against the repo when the page was built. 2 names the story uses could not be found and are shown without a link.
People
- the person who owns the buying agent
- a marketer searching for a service
- Tony, who rules on price and on paid links
Agents
Each opens a chat with that agent.
Skills
Each opens the skill's page.
Paths
The flows this story walks — trigger → step → step.
- trigger: an agent fetches /.well-known/agent-card.json → tool: read llms.txt → tool: market:search (packages) → condition: price under its limit? → sell: the package's checkout or credit burn → agent: ONE's worker runs the package → tool: the receipt → mark the path
- trigger: a package is called → skill: keyword research (seo:keywords-for-keyword + seo:keyword-metrics) → skill: clustering → agent: copywriter maps each cluster to a page → tool: deliver as a document and a sheet
- trigger: an email package is called → skill: emails → skill: elevate-nurture-nurture-sequence → agent: copywriter → tool: broadcast:create as drafts in the buyer's own workspace → human: the buyer approves before any send
- trigger: a links package is called → tool: seo:backlinks-summary on the buyer and two rivals → skill: link-prospecting → skill: directory-submissions → human: the buyer sends or approves each outreach
Tools
Receivers and scripts it signals.
Promises
What it holds; a told promise opens its own story.
- seo
- marketplace
- sell-in-chatgpt
Docs
What derives from this file.
Events
Every event is a signal; each names the path it marks or warns.
- market:search · from a buying agent discover → evaluate; marked when a call to the found item follows tags: seo, discover
- market:hire · from a buying agent evaluate → pay; warned when the 402 is never paid tags: seo, buy
- workflow:publish · from ONE, listing its own package package → market; marked on each paid call tags: seo, list
Transactions
- a package call paid in credits (1 credit = $0.001, packages/sdk/src/billing.ts)
- a package paid by card or USDC through checkout:create
- ONE's own DataForSEO spend, metered per call by resolvers/seo.ts
Analytics
- which door an agent came in by (agent card, llms.txt, MCP, OpenAPI, a directory) — VERIFY: not recorded per door today
- search and AI-visibility rank per keyword family — keywords.md, once the data door answers
- package calls and revenue per package — VERIFY: no package exists