App Configuration Surfaces

Use these names consistently in Shuuka documentation and product discussions.

Canonical Terms

Term	What it means	Scope	Driven by
App Global Settings	Owner-facing settings shared across all installed instances of the same app	app-wide for that owner	settings.json and settings-global.json
App Admin Pages	Custom owner tools such as exports, dashboards, moderation, or analytics	app-wide workflow pages	admin_pages in manifest.json
App Instance Settings	Per-installed-app sidebar settings such as title, colors, button labels, or layout choices	one installed app instance only	groups and placeholders in manifest.json

What To Use When

Need	Use
API key, integration token, or app-wide feature flag	App Global Settings
custom owner dashboard or export screen	App Admin Pages
title, button color, card copy, layout, or media for one card on the profile	App Instance Settings

The Important Difference

App Global Settings are shared across all installed instances of that app for one owner.

App Instance Settings are saved per installed app instance. If the owner adds the same app twice to the layout, each app can have different instance settings.

Builder Rule

Start with the lightest surface:

1. use App Global Settings for shared configuration
2. use App Instance Settings for per-card configuration
3. add App Admin Pages only for custom workflows