--- title: "Developer Guide" description: "Build, test, deploy, release, and publish a SotaAgents app from one maintainable project." url: "https://sotaagents.ai/manual/developer-guide" generated_by: "sotaagents-ldp" docs_index: "https://sotaagents.ai/manual/llms.txt" locale: "en" --- # Developer Guide Build, test, deploy, release, and publish a SotaAgents app from one maintainable project. - [What apps can do](https://sotaagents.ai/manual/developer-guide/what-apps-can-do): A SotaAgents app is a versioned capability package that extends the platform inside an organization and its workspaces. One app can contribute callable tools, reusable skills, n… - [Architecture philosophy](https://sotaagents.ai/manual/developer-guide/architecture-philosophy): SotaAgents deliberately separates the platform control plane from the app data plane. The platform knows the user, organization, workspace, installation, selected environment, e… - [Lifecycle & environments](https://sotaagents.ai/manual/developer-guide/lifecycle-and-environments): - [Sota CLI](https://sotaagents.ai/manual/developer-guide/sota-cli): Sota CLI is the supported developer interface. It scaffolds projects, validates manifests, builds native UI contracts, opens live Development sessions, creates immutable Staging… - [Create a project](https://sotaagents.ai/manual/developer-guide/create-a-project): sota init creates a current Manifest v3 app. Run it without --features and it asks which capabilities to scaffold; pass --features admin-screen,skill,backend,tool,tool-result-ui… - [Manifest explained](https://sotaagents.ai/manual/developer-guide/manifest-explained): manifest.yaml is the declarative contract between your app and SotaAgents. It describes what the app is, what it contributes, where its backend lives, which native modules the p… - [Workspace pages](https://sotaagents.ai/manual/developer-guide/workspace-pages): A workspace page is a full app-owned screen reached from workspace navigation. Core resolves the current app execution for the installed lane, owns routing and the mount boundar… - [User settings pages](https://sotaagents.ai/manual/developer-guide/user-settings-pages): A user settings page is an app-owned tab inside Account Settings. It is modal-local and appears only when Core has an explicit active workspace where the app is installed, enabl… - [Admin pages](https://sotaagents.ai/manual/developer-guide/admin-pages): An admin page is the same native page primitive placed in workspace administration. Use it for app configuration and operational controls, not ordinary member workflow. - [Tool views](https://sotaagents.ai/manual/developer-guide/tool-views): A tool-view replaces or enriches the visual representation of tool calls declared by the same app. Bind it with non-empty toolNames. Core passes one toolResult prop and preserve… - [Message parts](https://sotaagents.ai/manual/developer-guide/message-parts): A native message-part is an inline tool surface mounted below the relevant chat message. It uses the same ToolResultSurfaceProps, states, producer-lane context, toolNames, and o… - [Artifact surfaces](https://sotaagents.ai/manual/developer-guide/artifact-surfaces): An artifact surface owns the body of a durable side-panel view. Declare a stable app-namespaced artifactKind; Core uses it to resolve the current native module in that app lane… - [Workspace cards](https://sotaagents.ai/manual/developer-guide/workspace-cards): A card is compact app UI placed in the workspace assistant area. It receives no card-specific props; use platform hooks for context, data, and actions. - [Composer actions](https://sotaagents.ai/manual/developer-guide/composer-actions): A composer-action is a compact app-owned action beside the chat input controls. It is appropriate for opening app UI or starting an app workflow. - [Composer panels](https://sotaagents.ai/manual/developer-guide/composer-panels): A composer-panel is contextual app UI above the composer. It is the only surface bound to the public composer API, so it can observe the draft, make atomic edits, see pending de… - [useAppContext](https://sotaagents.ai/manual/developer-guide/use-app-context): useAppContext() is the primary runtime API for every hosted native surface. Import it from @sota/platform; it throws when no app surface provider is mounted. - [useAppFetch](https://sotaagents.ai/manual/developer-guide/use-app-fetch): useAppFetch() returns the mounted surface's authenticated data-plane fetcher. Pass an app-relative path and ordinary RequestInit; Core resolves it under the selected environment… - [useLocale](https://sotaagents.ai/manual/developer-guide/use-locale): useLocale() returns { locale, t } for the current mount. locale is the locale actually loaded for this app surface. t(key, values) reads the app's declared locale messages and i… - [useTheme](https://sotaagents.ai/manual/developer-guide/use-theme): useTheme() returns 'light' or 'dark' and re-renders with the host theme. It is read-only: apps adapt to the workspace theme; they do not mutate it. - [Platform UI components](https://sotaagents.ai/manual/developer-guide/platform-ui-components): @sota/platform/ui is the supported component library for native apps. These components inherit Core tokens, theme, focus behavior, portals, and accessibility defaults. Import fr… - [Platform icons](https://sotaagents.ai/manual/developer-guide/platform-icons): @sota/platform/icons exposes the stable icon names bundled for native apps: alert, check, chevronDown, chevronLeft, chevronRight, close, info, loading, search, settings, and war… - [Surface lifecycle](https://sotaagents.ai/manual/developer-guide/surface-lifecycle): useAppContext().lifecycle owns resources for one surface mount. Cleanup runs when the mount unmounts or its exact runtime identity changes. - [Platform UI bridge](https://sotaagents.ai/manual/developer-guide/platform-ui-bridge): useAppContext().ui lets app-owned UI ask the host to perform host-owned presentation. It contains primitives, not business workflows. - [useComposer](https://sotaagents.ai/manual/developer-guide/use-composer): useComposer(selector) is available only inside a hosted composer-panel and throws elsewhere. Import it from @sota/core/hooks. Select only the field a component needs so unrelate… - [Deferred tool results](https://sotaagents.ai/manual/developer-guide/deferred-tool-results): A tool backend may defer the result of the current tool call without creating a user message or asking the model to call it again. Core understands only an operation id and opaq… - [UI contract helpers](https://sotaagents.ai/manual/developer-guide/ui-contract-helpers): The generated @sota/platform package also exposes build-time contract metadata and one typed descriptor helper. Manifest v3 remains the registration authority. - [Local development](https://sotaagents.ai/manual/developer-guide/local-development): Local development uses two independent processes in two terminals. You own the app's watchers; the CLI owns the Development session and the tunnel that reaches your machine. Sot… - [Validate & test](https://sotaagents.ai/manual/developer-guide/validate-and-test): - [Deploy Staging](https://sotaagents.ai/manual/developer-guide/deploy-staging): The browser cannot safely or reproducibly load source files from a developer laptop. Deployment turns the declared app surface into immutable, content-addressed bytes that every… - [Release Production](https://sotaagents.ai/manual/developer-guide/release-production): Release promotes the exact current Staging artifact to Production. It does not rebuild, copy Staging data, or wait for release approval. The first Production release starts Priv… - [Publish to App Store](https://sotaagents.ai/manual/developer-guide/publish-to-app-store): A Production release and an App Store listing are separate decisions. Production can remain Private or be restricted to selected organizations without appearing in the public ca… - [Best practices](https://sotaagents.ai/manual/developer-guide/best-practices): Give tools one clear job, strict schemas, bounded timeouts, and safe failure modes. Avoid destructive actions unless essential. - [Developer troubleshooting](https://sotaagents.ai/manual/developer-guide/developer-troubleshooting): Useful commands: sota status, sota logs, sota manifest diff , and sota docs.