# Rules and suggestions

Every hard rule for an Atrium app on one page, then the suggestions that make an app feel at home in COHO.

Rules are required for COHO-built apps and checked when any app asks for a public listing. Suggestions are recommended for every app. Details for each rule are in the linked page.

## Rules

<Rule>
**Verify every signed call before acting on it.** Reject a bad signature, a changed body, path or method, or a timestamp more than 300 seconds old. Verify `lifecycle.setup` with the setup secret before storing anything. [Calls COHO makes to you](../../docs/calls-coho-makes-to-you/)
</Rule>

<Rule>
**Return 2xx from the setup path only when the app is ready.** A non-2xx response rolls the connection back. [Manifest](../../docs/manifest/)
</Rule>

<Rule>
**Keep secrets on the server.** Never put the API key, signing secret or setup secret in a browser, a query string, logs or your image. [How the app appears in COHO](../../docs/how-the-app-appears-in-coho/)
</Rule>

<Rule>
**Use references and Guids, never database ids.** Everything COHO sends or accepts identifies records by reference. [Calls you make to COHO](../../docs/calls-you-make-to-coho/)
</Rule>

<Rule>
**Ask only for the permissions the app uses**, and say what each one is for in the listing. [Permissions](../../docs/permissions-high-level/)
</Rule>

<Rule>
**Stay inside the rate limits** and back off on `429`. [Rate limits](../../docs/rate-limits/)
</Rule>

<Rule>
**Answer the health check.** [Health check](../../docs/health-check/)
</Rule>

<Rule>
**Screens inside COHO load `atrium.css` and use its tokens**: no external fonts, no brand colours that override the tokens, labelled inputs, nothing that relies on colour alone. See the design system's rules page.
</Rule>

## Suggestions

<Suggestion>
**Start from a sample** in your language rather than from scratch. [Starter samples](../../docs/official-connecting-kit-starter-samples/)
</Suggestion>

<Suggestion>
**Build and test on Playground first**, against demo data. [Playground](../../build-with-ai/playground/)
</Suggestion>

<Suggestion>
**Use the design system's components as they are.** Third-party apps may add their own brand mark and illustrations, but buttons, forms, tables and messages should look like the design system so managers know how they behave.
</Suggestion>

<Suggestion>
**Write the listing for managers, not developers**: what it does, what it needs, what runs in the background, and what it costs (flat monthly or per unit).
</Suggestion>

<Suggestion>
**Close the quick view with the bridge message** rather than your own close button outside the COHO frame. [How the app appears in COHO](../../docs/how-the-app-appears-in-coho/)
</Suggestion>