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.

Email

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 answers composio 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 the one-secrets worker (the OPENER binding), and setting it is Tony's fingerprint.
  • No DataForSEO number was read. text/keywords.md lists 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, which one.json and /marketplace show to every visitor. Removing them is a production write.
  • The old text/seo.md was the SEO engine plan (OpenSEO onto Composio). It is now text/seo-plan.md with 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)

  1. robots.txt route on one.ie, ported from template/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.)
  2. /.well-known/api-catalog (copy the template's), /.well-known/mcp.json, and a root /.well-known/agent-card.json built from the registry. Rows 1–2.
  3. Fix /u/one/.well-known/agent-card.json (404: no one/agent.md in R2).
  4. /marketplace.json, a public read of the market as data. Row 4.

Wave 2 — the data door (Tony's fingerprint once)

  1. A valid Composio key, set as COMPOSIO_API_KEY on the one-secrets worker. Production reads it there: the web app calls Composio through the OPENER binding, bound since 2026-11-08 (one.ie/web/wrangler.toml:372-384), not from its own env. The local key in .dev.vars answers the same 401. Then seo-live.test.ts green. Row 8.
  2. 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.
  3. CLI oneie seo verbs. Row 9.

Wave 3 — the packages (Tony rules on prices and on paid links)

  1. 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.
  2. workflow:publish each at the ruled price. Row 5.
  3. The Packages shelf on /marketplace and a /packages/<slug> page each. Row 6.
  4. Clean the probe rows off market:list.
  5. A walk: a fresh agent with only the domain finds a package, pays and gets its deliverable, timed, as text/agent-path.md walks are.

Wave 4 — the pages and the listings

  1. /docs/signals, /docs/dsl, /docs/ontology, /docs/surfaces, /receivers/<namespace>, each with a .md twin. Row 7.
  2. 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.
  3. 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.json and api-catalog are 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 numbers
  • text/seo-plan.md — the SEO engine: DataForSEO and GSC through Composio, rank tracking, audits, UI
  • text/seo-todo.md — the engine's cycles
  • text/billing-seo.md — the three SEO meters and their real cost
  • text/marketplace.md — the deal engine behind market:*
  • text/agent-path.md — how an agent walk is timed and scored
  • text/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

Paths

The flows this story walks — trigger → step → step.

  1. 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
  2. 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
  3. 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
  4. 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

Promises

What it holds; a told promise opens its own story.

  • seo
  • marketplace
  • sell-in-chatgpt

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