Developer Guide
Build, test, deploy, release, and publish a SotaAgents app from one maintainable project.
01What apps can doA 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…02Architecture philosophySotaAgents deliberately separates the platform control plane from the app data plane. The platform knows the user, organization, workspace, installation, selected environment, e…03Lifecycle & environments04Sota CLISota CLI is the supported developer interface. It scaffolds projects, validates manifests, builds native UI contracts, opens live Development sessions, creates immutable Staging…05Create a projectsota 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…06Manifest explainedmanifest.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…07Workspace pagesA 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…08User settings pagesA 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…09Admin pagesAn admin page is the same native page primitive placed in workspace administration. Use it for app configuration and operational controls, not ordinary member workflow.10Tool viewsA 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…11Message partsA 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…12Artifact surfacesAn 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…13Workspace cardsA 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.14Composer actionsA 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.15Composer panelsA 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…16useAppContextuseAppContext() is the primary runtime API for every hosted native surface. Import it from @sota/platform; it throws when no app surface provider is mounted.17useAppFetchuseAppFetch() returns the mounted surface's authenticated data-plane fetcher. Pass an app-relative path and ordinary RequestInit; Core resolves it under the selected environment…18useLocaleuseLocale() 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…19useThemeuseTheme() 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.20Platform 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…21Platform 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…22Surface lifecycleuseAppContext().lifecycle owns resources for one surface mount. Cleanup runs when the mount unmounts or its exact runtime identity changes.23Platform UI bridgeuseAppContext().ui lets app-owned UI ask the host to perform host-owned presentation. It contains primitives, not business workflows.24useComposeruseComposer(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…25Deferred tool resultsA 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…26UI contract helpersThe generated @sota/platform package also exposes build-time contract metadata and one typed descriptor helper. Manifest v3 remains the registration authority.27Local developmentLocal 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…28Validate & test29Deploy StagingThe 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…30Release ProductionRelease 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…31Publish to App StoreA 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…32Best practicesGive tools one clear job, strict schemas, bounded timeouts, and safe failure modes. Avoid destructive actions unless essential.33Developer troubleshootingUseful commands: sota status, sota logs, sota manifest diff <left> <right>, and sota docs.
