# Agent Instructions — Maksutin

This document describes how AI agents can interact with https://maksutin.fi, the site of the
Maksutin commerce platform.

**maksutin.fi is not a store.** Nothing is for sale here. It is the platform's own site:
product information, pricing, case studies and the blog. If you are shopping on behalf of a
user, you want an individual Maksutin *store*, not this host.

## For Personal Shopping Assistants and Agents Acting On Behalf of a User

Install the Maksutin skill: [https://maksutin.fi/SKILL.md](https://maksutin.fi/SKILL.md)

It is the recommended way for browser-using agents, "buy-for-me" agents and personal shopping
assistants to transact with Maksutin stores. It covers:

- Reading a store's agent surface from its hostname alone — no credentials
- Catalog search and product/variant lookup
- Cart building with server-side price recalculation
- A `checkout_url` the buyer opens themselves to authorize payment

There is a CLI for the same surface:

```bash
npm install --global @phenomenal-development/maksutin-cli
maksutin discover --shop <store-host>
```

**The buyer always completes payment.** Maksutin stores issue no delegated payment instruments
and expose no agent-completed checkout. An agent's last step is a cart and a link.

## Finding a store

Maksutin operates no central marketplace, and there is **no endpoint that searches every
Maksutin store at once**. You work against one store at a time, addressed by its hostname —
either a custom domain or a `<store>.maksutinkauppa.fi` subdomain. Ask the user which store
they mean rather than guessing a hostname.

Once you have a host, everything else resolves from it:

- `https://<host>/agents.md` — that store's own agent instructions
- `https://<host>/.well-known/ai-shopping.json` — its machine-readable manifest
- `https://<host>/.well-known/ucp` — its UCP merchant profile
- `https://<host>/mcp` — its public MCP endpoint (Streamable HTTP, no auth)
- `https://<host>/api/storefront/products` — its public REST catalog

A store that answers `404` on those has not switched agent shopping on; the error body's `code`
distinguishes `ai_shopping_disabled` from `shop_not_found`.

## Reading this site

- Agent skills index: `GET /.well-known/agent-skills/index.json`
- Shopping skill: `GET /SKILL.md`
- Platform overview skill: `GET /.well-known/agent-skills/maksutin-overview/SKILL.md`
- WebMCP tools skill: `GET /.well-known/agent-skills/maksutin-tools/SKILL.md`
- API catalog (RFC 9727): `GET /.well-known/api-catalog`
- OpenAPI description: `GET /openapi.json`
- Sitemap: `GET /sitemap.xml`
- Pricing: `GET /hinnasto`
- Privacy policy: `GET /tietosuojaseloste`

Pages return HTML by default and Markdown when you send `Accept: text/markdown`.

## Platform

Maksutin is a Finnish all-in-one platform for online stores, event ticketing, appointment
booking and websites, operated by Phenomenal Development Oy.

- Start a store: https://maksutin.fi
- Pricing: https://maksutin.fi/hinnasto
- Support: asiakaspalvelu@maksutin.fi
- Shopping skill: https://maksutin.fi/SKILL.md
- CLI: https://www.npmjs.com/package/@phenomenal-development/maksutin-cli