Review guidelines
What gets approved automatically and what a person reviews, what reviewers check, common reasons for rejection, branding and data rules, and when versions are yanked.
The store exists so people can install an app without worrying about it. These guidelines are how we keep that promise. They're short on purpose; when in doubt, ask yourself whether a careful user who read your listing would be surprised by what your app does.
#Automatic vs. human review
Every upload runs the automated checks — the same validator as chataway validate --store. Then:
| Situation | Review |
|---|---|
| First version of an app | Human |
Adds grants, domains, accounts or scopes, adds file params, adds a required app or connector (requires), or changes mcpUrl | Human |
| Adds a folder or an "Open with" handler, or widens one's access or file types | Human |
Adds or changes contributes.instructions, a prompt kit, a folder's label or reason, or an "Open with" label | Human — reviewers read the text in full |
| Publisher's domain isn't verified | Human (every version) |
| A check flagged something (e.g. code that looks obfuscated) | Human |
A verified local app (ships server code) | Human, every version — reviewers read the code, the diff, skills and the exec reason |
| Verified publisher, nothing new asked for | Automatic — published in seconds |
Reviewers see your manifest, the permissions diff against your last approved version (highlighted), the full manifest diff, the file list, your screenshots and README, and the check report. For apps that use app API 4 they also see your instructions and every prompt kit in full, your folders and their reasons, your "Open with" handlers, your storage zones and the new grants (models, folders, agent, chats).
#What reviewers check
#Honesty
- The listing matches the app. Name, description, screenshots and README describe what the app actually does — no features that don't exist, no screenshots of other products.
- Permissions are explained. Each grant, account and scope has a plain sentence in
permissionsthat a non-developer understands. "Receive images you choose to upload to Acme", not "files:receive". - Tool descriptions are accurate. They're read by the agent; a description that says "read-only" for a tool that writes will be rejected.
#Consent and gestures
- Side effects are behind
confirm. Uploading, publishing, sending, posting, deleting, and spending money or credits all need an approval card, and its title and body say what will happen. "Upload 3 images to Acme? They will be public." - No dark patterns on cards. No pre-emptive "always allow" wording, no fake urgency, no approve buttons labelled Cancel.
- Forms ask for what the tool needs — never passwords, API keys, card numbers or one-time codes.
#Instructions and prompt kits
contributes.instructions goes into every chat of a project where your app is on, for every provider. Prompt kits fill the user's composer. Both are text an agent follows, so a reviewer reads every word, in every version that changes them.
- No impersonation. Don't present your app as Chataway, Otto, the user or another app, and don't tell the agent it is someone else.
- No hidden instructions. Nothing may tell the agent to send files, chat content, keys or anything else to your server or anywhere else unless the user asked for it in that chat. No text hidden in odd whitespace, invisible characters or encodings.
- Nothing that overrides the user. Describe your app, its files and its tools. Don't tell the agent to ignore the user, to always use your tools, to avoid other apps, or to change how it handles safety.
- Stay on your own subject. Instructions are about your app. A notes app explains its notes folder; it doesn't give the agent opinions about code style.
- Kits do what their title says. A kit called Summarize summarizes. It fills the composer; the user reads it and sends it.
#Folders, AI and agent runs
- Folder reasons are honest and specific. Say what you read and what you write: "Sketch Notes opens and saves your notes here." Use
access: "read"unless you edit files, and list only the file types you open. - Suggest your own folder.
notes/orsketches/, not the project root. - Model calls serve the user. Use the user's AI for what your app does, from something the user did. No background loops that use up the user's daily limit.
- Agent runs are scoped. Start a run from a click, on the folders the user granted, with a task that says what it will do. Tidy notes tidies notes; it doesn't rename the folder or delete files it didn't mention.
- App chats are the user's. Create a chat when the user asks for one, and don't send in it on their behalf without their click.
#Storage zones
- The user's work is the user's. Exports, documents and anything else the user made go in a
userzone. Useinternalonly for your app's own data (caches, indexes, settings). - Zones protect integrity, not secrets. They keep agents from changing your internals. They don't hide anything from the person who owns the Mac. Keep secret prompts, keys and proprietary logic on your server — see storage zones.
#Least privilege
- Only the grants you use.
project:writefor an app that never saves to the project will be rejected. - Only the domains you need. Each one should be explainable; broad wildcards need a reason (
*.cdn.example.comfor sharded CDNs is fine). - Minimal OAuth scopes. Don't ask for
adminwhenassets:writewill do. acceptandmaxBytesfit the tool. An image uploader doesn't accept*/*.
#Code
- Readable panel code. Minified is fine. Obfuscated JavaScript (string tables,
evalof decoded strings, packed code) is flagged and usually rejected. Reviewers need to be able to see what your panel does. - No remote code. The panel may not download and execute scripts (the CSP prevents most of it; don't try to get around it with
evalof fetched text). - No tracking. No third-party analytics, fingerprinting or ad SDKs in the panel.
#Data use
- Data minimization. Your server receives files and arguments the user chose to send; use them for the tool's purpose and don't keep them longer than needed.
- A privacy policy linked from your
homepagethat covers data received through Chataway. - No training on user content without an explicit opt-in on your own service.
- No selling or sharing of data received through the app.
- Pseudonyms stay pseudonyms. Don't try to link
X-Chataway-*ids across apps or re-identify users beyond your own account system.
#Branding
- Your own name and art. No names or icons imitating Chataway, Otto, the built-in apps, or another listed app. The name may not contain Chataway.
- A real icon, not the scaffold's placeholder; a mark that reads at 16 px.
- An accent that's visible in both light and dark themes.
- Screenshots of your app in Chataway, current, without misleading edits.
#Quality
- It works. Reviewers install it, connect the account, and call each tool. A tool that errors on the obvious first call is rejected.
- Helpful errors. Error messages tell the agent what went wrong and what to do.
- Reasonable speed. Tools answer within the 120 s limit; long jobs use a status tool.
#Common rejection reasons
| Reason | What to do |
|---|---|
A tool uploads or posts without confirm | Add confirm with a clear title and body. |
permissions don't explain a grant or scope | Add a plain sentence for each. |
| Unused grant or domain | Remove it. |
| Placeholder icon or no screenshots | Add real branding. |
| Obfuscated panel code | Ship readable (minified is fine) code; include source maps if you like. |
| Listing promises features that aren't there | Describe what the app does today. |
| Instructions tell the agent to do something the user didn't ask for (send data, always prefer your tools) | Describe your app and its files; leave the choices to the user. |
| A folder reason that doesn't say what happens to the files | Say what you read and what you write. |
The user's own work sits in an internal zone | Put it in a user zone. |
| The app id doesn't match the publisher | Use an id under your verified domain. |
| The server was down during review | Keep mcpUrl up; include a test account in your reviewer notes if sign-up is gated. |
Rejections come with the reviewer's notes, in the dashboard and in chataway status. Fix the issue, bump the version, and publish again.
#Yanking
The review team can yank a published version — for example when it's broken in a way that harms users, misuses data, or was compromised. A yanked version is added to the signed revocation list, and every Mac disables it at its next check (hourly and at startup). You're notified with the reason.
You can ask for your own version to be yanked from the dashboard — for example when you shipped a bug that uploads to the wrong account. Then publish a fixed version.
Serious or repeated violations can lead to an app being suspended (removed from the store and disabled) or a publisher being suspended.
#Asking for help
If you're unsure whether something is allowed, ask before you build it — from the developer dashboard. Include your app id and what you're planning.