A governed operating system for expert work with AI

Request flow

Operating model

The Studio treats system ownership as a connected set of questions, not a collection of dashboards. Each question resolves to a governed record and an explicit place to act.

Candidate acceptance records only an immutable Studio review head and append-only decision. It does not replace canonical source or initialize later runs from the candidate. Git push or merge and production deployment remain separate explicit controls.

Trust boundaries

1. auth.categori.se authenticates with the existing categorise Cognito pool. The dedicated public SPA client uses authorization code flow with PKCE.
2. API Gateway validates the token issuer and this app client's audience. Lambda then requires the configured single-operator subject plus ProjectOwner or PlatformAdmin; administrative routes additionally require PlatformAdmin.
3. CloudFront is the only reader of the private web bucket. Source and data buckets block public access, use S3-managed encryption, and retain versions.
4. Self-hosted inference listens only on the stopped-by-default workstation's loopback address. The background runner reaches it on the same host; operator sessions reach the workstation through SSM. It is not a public application endpoint.
5. Hosted-provider authentication is local to the development workstation. Credential caches are never copied to S3 or accepted by the studio API.
6. Agent behavior/context is a governed asset; the active provider/model is a separate revisioned next-turn route. No running turn silently falls through to another engine.

One shell, many engines

The editor owns the visible conversation, selected files, approvals, and handoff checkpoint. A reviewed adapter supplies inference: local Ollama/vLLM, subscription-backed Codex, Kiro ACP, or Groq behind the owned agent loop. Switching providers preserves user-visible goals, decisions, source revision, checks, and approved-context identity—not hidden vendor reasoning.

This keeps the vocabulary small: application, agent profile, route, run, evaluation, and promotion. The Developer page exposes the model shelf; Settings controls permission; provider login remains a separate local fact.

Progressive context, not uncontrolled self-modification

An agent reads approved context and produces run traces, evaluation evidence, and candidate memories. Candidates become active context only after review or an evaluation gate. This preserves a causal history: every behavior change can be tied to a source artifact, prompt/config revision, adapter, and evaluation result.

source data → immutable run trace → candidate memory → evaluation → approved context
                                ↘ rejected candidate (retained for diagnosis)

The S3 layout keeps those phases separate:

s3://ai.studio/projects/<slug>/source/
s3://ai.studio.data/projects/<slug>/datasets/
s3://ai.studio.data/agents/<slug>/context/candidates/
s3://ai.studio.data/agents/<slug>/context/approved/
s3://ai.studio.data/agents/<slug>/evaluations/
s3://ai.studio.data/agents/<slug>/models/adapters/
s3://ai.studio.data/projects/<application>/context/approved/
s3://ai.studio.data/projects/<application>/runs/<run-id>/

For source changes, the run's candidate tree and manifest live under the application's immutable revision prefix. An explicit approval records that review URI in head_source_uri and advances source_revision; it does not mutate canonical source, affect the next run's worktree, or deploy an application.

s3://ai.studio/projects/<slug>/source/                         immutable execution snapshot mirror
s3://ai.studio/projects/<slug>/revisions/<run-id>/source/      immutable candidate tree
s3://ai.studio/projects/<slug>/revisions/<run-id>/manifest.json candidate identity

Deployment layers

The default deployment creates only the control plane:

AWS_PROFILE=categorise scripts/deploy.sh

Filesystem synchronization is explicit and three-way conflict-gated. The Projects panel renders the exact manifest-registered commands; for Docs Repo they are:

AWS_PROFILE=categorise scripts/sync-project.sh status /home/aaron/framework/ai/docs-repo \
  s3://ai.studio/projects/docs-repo/source/ source
AWS_PROFILE=categorise scripts/sync-project.sh baseline /home/aaron/framework/ai/docs-repo \
  s3://ai.studio/projects/docs-repo/source/ source
AWS_PROFILE=categorise scripts/sync-project.sh pull /home/aaron/framework/ai/docs-repo \
  s3://ai.studio/projects/docs-repo/source/ source
AWS_PROFILE=categorise scripts/sync-project.sh push /home/aaron/framework/ai/docs-repo \
  s3://ai.studio/projects/docs-repo/source/ source

Source sync never deletes either side. It permits an initial reviewed seed and routine one-sided changes, but stops on divergent edits or recorded-path removal. After the first push, Check source verifies the private prefix through the authenticated API and initializes canonical lineage. Until then, the application and deployment administration stay visible but file browsing and agent runs remain closed.

The current self-hosted Agent Studio runs Ollama on an on-demand c6i.xlarge EC2 workstation that is stopped by default and powers off after background work; its four-hour timer is a fallback. The fixed-performance instance costs $0.17/hour only while active and avoids the T3 credit throttling observed during live model evaluation. CPU/GPU Batch workers are a separate optional Spot layer and are not implied by workstation state. Their deploy commands, lifecycle controls, prerequisites, and rollback procedure are documented in the source repository's README.md.