# murakumo Go and first-party ads

This document records what exists after the first /go ship. It is not a
growth deck. There is no fill-rate, GMV, or partner list here because none
of those exist yet.

**This surface is new.** It did not exist before this change. Do not read
older homepage or GTM copy as if /go or an ad network were already live.

## What exists

| Surface | What it is |
|---|---|
| `https://murakumo.cloud/go` | Distinct unpaid inference UI plus a visible first-party ad unit. Static HTML in `public/go.html`. |
| `https://murakumo.cloud/advertise` | Advertiser apply form. Intake only. Static HTML in `public/advertise.html`. |
| `GET /api/v1/ads/placement` | Returns one placement. Query may include `placement` (or `id`) and `locale` only. |
| `POST /api/v1/ads/apply` | Stores an application. No payment. |

The homepage try box (`#landing-try` / `try-chat!`) is unchanged as a
product surface. /go is a second page, not a silent restyle of that box.

Inference on /go reuses the same unpaid browser path: `POST
/api/v1/chat/completions` with `x-murakumo-app: cloud-murakumo` and no
bearer token. Model `qwen3.8-27b`. `max_tokens` ≤ 400 (the Worker clamps
the unpaid header path). Programmatic calls without a token still 401
when the access gate is on.

## What does not exist

- No ad network partners, brands, or logos.
- No approved listed inventory at ship time.
- No third-party ad tags, retargeting pixels, or query-text auctions.
- No self-serve approval, no billing for ads, no measured fill rate, no GMV.
- No change to paid x402 (`POST /x402/v1/chat/completions`, $0.01 USDC) or
  to Stripe credits checkout.
- No NEXUS / infer-memory token required on /go.
- Hardware (murakumo Node) is a different storefront. This
  Service is operated by Kotoba Labs Inc. Sales: Ryo Awai.

## Privacy rule

Ads must never send prompt or completion text to advertisers or any third
party.

The placement request is allowed to carry only:

- placement id (`go-sidebar` today)
- locale
- empty/house vs operator-approved inventory

It must not carry the user message. The Worker ignores prompt-like query
keys (`prompt`, `message`, `q`, …) and does not echo them. Applications
store org, email, site URL, placement preference, and notes — never
prompts.

Placement ads are first-party only. The slot is HTML rendered from
murakumo's own JSON. There is no external creative iframe or script.

## House vs listed

| `kind` | When | What the slot says |
|---|---|---|
| `house` | Zero approved listings for that placement | House copy: “This placement is available on murakumo.cloud”, link to `/advertise`. Label: first-party house placement — **not** a paid ad. |
| `listed` | An operator has approved a listing for that placement | The approved advertiser name, href, and copy. Still first-party served. |

Empty inventory is honest house copy. The implementation must not invent a
partner to avoid an empty slot.

## How to approve a listing (v1, manual)

Applications land in the existing Worker KV binding `INFER_MEMORY_KV`
under `ads:apply:<id>`. That is reuse of storage this Worker already has,
not a new vendor. No cacao. No payment.

To show a listed unit, an operator later sets **one** of:

1. Wrangler var `MURAKUMO_ADS_LISTED` — a JSON array, or
2. KV key `ads:listed` — the same JSON array.

Shape (only fields that are used):

```json
[
  {
    "placement": "go-sidebar",
    "advertiser": "Example Org",
    "href": "https://example.invalid",
    "copy": "Copy the advertiser actually supplied"
  }
]
```

There is no automatic promotion from `ads:apply:*` to `ads:listed`.
Review is manual. Do not put secrets in the listing JSON. Do not put
real partner names in this repo until one is actually approved.

Env listings win over the KV key when the env value parses to a non-empty
approved list.

## Paid paths stay unchanged

- x402 offer and unpaid 402 challenge are the same.
- infer-memory still requires its existing Nexus payment headers.
- Stripe checkout, credits SKUs, and webhook settlement are untouched.

/go is an unpaid browser path with a visible first-party ad. It is not a
discount on x402 and not a credits grant.