Publish With Studio

Use the Studio path when you want the full guided Cloud V1 workflow in the native macOS SwiftUI Studio. Studio shows the Cloud deployment inventory, the selected cloud work view, hosted chat, Activity, provenance, observation append, health, usage metrics, and replay/export state in one operator surface.

If you need a scriptable flow instead, use the Cloud CLI path.

1. Open A Verified App

Install JacqOS and open Studio from your app directory:

curl -fsSL https://www.jacqos.io/install.sh | sh
jacqos scaffold appointment-booking
cd appointment-booking
jacqos verify
jacqos studio

On first run, Studio opens the workspace picker. Open the app you just verified or one of the bundled demos. Do not publish until the local verification status is green.

Open the Cloud panel and click Sign in. Studio uses the configured WorkOS-backed management plane and a code-based Magic Auth flow. You receive a code by email, enter it in Studio, and Studio completes the session through the local Studio API. There is no browser requirement for the default macOS Studio login path.

The management URL is app configuration, not a user setting. In local development, Studio uses the production app default or JACQOS_MANAGEMENT_URL or JACQOS_LIVE_MANAGEMENT_URL. If none is configured, Cloud account actions show a blocking configuration error instead of falling back to a local fixture identity.

For automated auth tests, coding agents use AgentMail. The runner maps the secret value from JACQOS_AUTH_TESTING_EMAIL_API_KEY into the AgentMail SDK process, reads structured email fields, extracts the WorkOS code, completes the Studio session, and writes a redacted receipt. The variable name is safe to document; the value is not.

3. Select The Cloud Scope

In the Cloud panel, select or create:

the project that owns the app,
the app identity,
the environment you want to publish into, such as prod.

The selected scope is organization-bound. If your WorkOS session belongs to a different organization, management writes fail before any runtime command is dispatched.

4. Publish, Deploy, And Promote

Click Publish from the Cloud panel. Studio runs the same guarded sequence the CLI exposes:

verify the local package,
deploy the verified package handoff,
promote the package as the live evaluator,
prepare a scoped runtime token,
inspect the promoted endpoint.

Shadow or failed packages cannot execute effects. Only the promoted evaluator for the selected app and environment handles runtime observations. Pause, rollback, and archive actions are available from the Cloud deployment row when the deployment lifecycle allows them.

5. Choose A Cloud Work View

After promotion, choose the cloud deployment as the current work view. A cloud work view carries a stable hosted identity:

project, app, and environment,
lineage id,
evaluator digest,
package digest,
worldview id,
activation epoch,
current hosted observation head.

When this work view is selected, Studio routes chat, Activity, provenance, and observation append through the hosted runtime projection instead of the local development projection.

6. Chat With The Hosted App

Use the same chat surface you use locally. In a cloud work view, Studio sends the chat request with hosted target identity and reads the hosted policy projection. Chat events are recorded in Activity with cloud deployment context, so you can tell which lineage, evaluator, package, and activation produced the answer.

LLMs remain tools, not drivers. Model output still enters JacqOS through candidate or proposal evidence and must pass ontology acceptance before it can become trusted fact or executable intent.

7. Inspect Activity And Provenance

Open Activity to see hosted lifecycle events, chat turns, observation append receipts, projection lag, effect retries, and reconcile-required states. Open Provenance to follow hosted facts, intents, and effects back to the observations and runtime receipts that produced them.

There is no separate debug database to trust. If Studio shows hosted state, it came from hosted observations, evaluator digests, package digests, runtime receipts, and exportable provenance neighborhoods.

8. Append Observations With The Cloud Warning

Studio can append observations into the selected cloud lineage, but the action is intentionally guarded:

the target must be a cloud work view,
the selected write policy must allow the observation,
the hosted refresh must be available and current,
local package identity must match the hosted activation,
you must acknowledge that this is an immutable hosted append.

Rejected appends are explicit. Studio reports policy denial, stale hosted projection, missing package identity, missing auth, revoked token, or runtime failure without silently falling back to local append.

9. Watch Deployments, Health, And Metrics

The Cloud panel lists deployments across your selected organization. Each row shows lifecycle, active package/evaluator identity, activation state, health, last activity, and top-level metrics such as request count, observation count, effect count, storage bytes, degraded/error counts, and last replay-export status.

Metrics are operational summaries. They help you operate the hosted runtime, but they are not JacqOS facts and do not alter replay.

10. Export And Replay Hosted Evidence

Studio is the fastest inspection path, but replay remains the proof boundary. Export hosted evidence when you need a CI artifact, audit handoff, or clean local reproduction of a hosted lineage.

Use the Cloud CLI replay-export step for the exact command shape. Replay must recompute the same package digest, evaluator digest, mapper-output digests, facts, intents, effects, and provenance. If identity drifts, treat the export as failed evidence.

Studio Action Reference

Action	Studio surface	What it does
Sign in	Cloud panel	Starts code-based WorkOS Magic Auth and stores support-safe session metadata.
Publish	Cloud panel	Verifies locally, deploys the package handoff, promotes it, and checks the endpoint.
Select work view	Cloud deployment row	Makes the hosted lineage the active chat, Activity, provenance, and append target.
Chat	Chat composer	Uses the selected hosted worldview projection and records cloud chat Activity.
Activity	Activity tab	Shows hosted lifecycle, chat, append, effect, lag, retry, and reconcile events.
Provenance	Provenance view	Shows hosted facts, intents, effects, and provenance neighborhoods.
Append observation	Observation modal	Requires write policy, package identity, current hosted refresh, and explicit warning acknowledgement.
Pause	Cloud deployment row	Stops effect execution for the active activation while preserving exported evidence.
Rollback	Cloud deployment row	Promotes a previous eligible package digest as the active activation.
Archive	Cloud deployment row	Retires a deployment record from normal active use.
Metrics	Cloud dashboard	Shows health and usage summaries, not canonical app facts.
Export	Cloud dashboard or CLI	Produces hosted evidence for clean local replay.

Next Steps

Cloud CLI path for scriptable publish, lifecycle, observation, and replay-export commands.
Cloud Troubleshooting and Security for failure ids, token boundaries, stale activation handling, and support-safe data handling.