AGENTS.md

sollar create-mini-app writes an AGENTS.md. This page explains what belongs in it and why the companion CLAUDE.md contains exactly one line.

The two-file pattern

AGENTS.md      ← every instruction
CLAUDE.md      ← @AGENTS.md

AGENTS.md is the filename Codex, Cursor, Jules, Factory and Aider look for. Claude Code reads CLAUDE.md and does not read AGENTS.md.

CLAUDE.md

@AGENTS.md

One source, one pointer. The alternative — the same instructions written into both files — drifts within a month, and nothing tells a reader which copy is current.

What the scaffold writes

AGENTS.md

# Acme ERP — a Sollar mini app

## What this is

A mini app that runs inside the Sollar superapp: a signed web package, served from its own
synthetic origin, with capabilities declared in `manifest.json`.

Reference: https://miniapp.sollar.com/llms.txt

## Rules that are not negotiable

- **The client is not an authority.** `sollar.identity.get()` is for drawing UI. Every
  authorisation decision happens on the backend, against the token, every time.
- **The manifest is the ceiling.** A permission or a host not declared in `manifest.json`
  cannot be obtained at runtime. Adding one means a new version, not a code change.
- **No secret reaches this codebase.** No client_secret, no API key, no signing key, no
  refresh token — not in .env, not in a config file, not in a comment. Call
  `sollar.auth.getToken()` before each use.
- **Device capabilities are Web APIs, not bridge methods.** Camera is
  `navigator.mediaDevices.getUserMedia`. Location is `navigator.geolocation`. If you are
  reaching for `sollar.<device thing>()`, it does not exist.
- **There is no payment API.** A mini app cannot take money in-app on either platform.
- **The backend cannot post into an encrypted room.** Use `sollar.message.send()` from the
  user's client, or an agent that is a member of the room.

## Before you write code

Read these, in this order:
1. https://miniapp.sollar.com/reference/manifest.md
2. https://miniapp.sollar.com/reference/bridge-api.md
3. https://miniapp.sollar.com/guides/authentication.md

Do not guess the bridge version. Run `sollar --version`.

## This project

- Backend: https://erp.acme.example — declared in `manifest.network.connect`
- Auth mode: sollar-exchange, audience `acme-erp-backend`
- Actions: see `manifest.json`. Every one needs a handler in `src/actions.js`.

## Before you say you are done

    npx sollar validate --strict
    npm run test:unit
    npx sollar test --conformance

`validate --strict` runs the same checks as the submission gate. If it fails, the work is not
done.

Why each rule is there

Each line in that file corresponds to something an agent gets wrong reliably.

Rule	The failure it prevents
The client is not an authority	An agent reads app_user_id from the bridge and authorises on it. It looks correct and is the defining vulnerability of this platform class.
The manifest is the ceiling	An agent adds a fetch to a new host and cannot understand why it fails. ERR_HOST_NOT_ALLOWED is not a bug.
No secret in the codebase	An agent asked to “configure the API key” will write it into .env unless told otherwise, and it will be committed.
Web APIs, not bridge methods	Invented methods are the most common single failure. sollar.getLocation() is exactly what a well-trained model expects to exist.
No payment API	An agent that knows WeChat will reach for requestPayment.
Encrypted rooms	The obvious notification design is a server-side post, and it silently does not work.

Keep it short

An instruction file competes for context with the code the agent needs to read. A 400-line AGENTS.md is worse than a 60-line one, because the important rules are diluted.

The test for a line: could the agent derive this from the code? Directory layout, dependency list, “this file handles routing” — all derivable, all wasted tokens. What belongs is what the code does not say: the magic value, the counter-intuitive library behaviour, the product decision, the lesson from an incident.

Point at URLs, do not copy

Read https://miniapp.sollar.com/reference/bridge-api.md before calling any sollar.* method.

Not:

The bridge API has the following methods: sollar.identity.get() returns…

A copied API surface is a copy that will be wrong after the next release, sitting in a file the agent trusts. Link to the .md twin and it is always current.

Add what is specific to you

The scaffold cannot know your project. Add:

• Domain vocabulary. If “approval” means something specific in your organisation, say so.
• Authority limits. “An agent may approve up to €5,000; above that a human approves directly.”
• What is irreversible. If an action releases an order to a vendor, the agent should know before it writes the handler, not after.
• Anything an incident taught you. These are the most valuable lines in the file and the ones nobody writes down.

What not to put in it

• Secrets. Ever, in any form, including “the key is in 1Password item X” written as a value.
• Duplicated documentation. Link to it.
• Directory listings. The agent can run ls.
• Instructions that contradict the platform. “Skip validation to save time” produces a mini app that fails at submission, having wasted the time it saved several times over.