# Artifacts, Assets, and Workspaces

Use this guide to organize durable work, review generated output, manage
reusable files, collaborate on drafts, and publish only an approved live
version.

## Product model and access

- A **workspace** groups instructions, documents, skills, chats, apps, and
  outputs for one business outcome.
- An **artifact** is a durable saved output such as a document, report, image,
  data file, dashboard, app, tool, or hosted MCP server.
- An **asset** is a reusable tenant file referenced by chat, workspaces,
  branding, artifacts, or coding tasks.
- A **draft**, an immutable **version**, and the **live** artifact are different
  states with different access and rollback behavior.

Open **Apps & Workspaces** at `/projects`, **Assets** at `/assets`, or a specific
artifact at `/artifacts/:id`. Visibility and write controls depend on tenant
capabilities, ownership, direct sharing, workspace membership, and live viewer
policy.

## Create and organize a workspace

1. In **Apps & Workspaces**, choose **New workspace**.
2. Give it a business-outcome name and concise description.
3. Open the workspace and add stable instructions or documents.
4. Bind only the approved skills needed for its repeatable workflows.
5. Start the workspace main chat or a bounded thread.
6. Save or move owned apps and outputs into the workspace.
7. Use **Sharing & access** to add only the intended collaborators.

Choose **All workspaces** or a specific workspace before filtering. The
**Apps & outputs** heading repeats the active scope and item count so the
selected workspace is unambiguous. Artifact-type, creator, status, ownership,
sort, and text filters apply inside that scope. Clear filters or choose another
workspace before concluding an item is missing. **Unfiled** remains a separate
table for apps and outputs with no workspace; only owned items can be moved.

Each artifact row has an action menu that opens **Item details**, **Tests**, or
**Problems** directly. Operators with artifact write access also see
**Artifact symbol**. These links open the selected drawer on the artifact page;
they do not create another artifact or change its live version.

### Choose workspace and artifact symbols

Workspace owners can open the workspace menu and choose **Workspace symbol**.
Artifact owners, editors, and co-authors can choose **Artifact symbol** from an
artifact row or artifact action menu. Upload a square PNG, JPEG, WebP, or GIF
smaller than 10 MB, or choose **Use default** to restore the generated symbol.

The uploaded image becomes a tenant asset and the resource stores its asset
identity. View-only collaborators can see the symbol but cannot change it. If
upload or save fails, the current symbol remains unchanged; retry from the same
resource after confirming write access and file type.

### Rename, archive, restore, or delete

The owner can rename the workspace, change its symbol, or archive it. Archiving
removes it from active navigation without deleting its content or audit
history. Use `/projects/archived` to restore it.

Permanent deletion is a separate irreversible workflow. Topline first
inventories apps, artifacts, chats, tasks, schedules, documents, skills, and
other dependencies. Deletion remains blocked while dependencies or active work
make it unsafe. When eligible, the operator must type the exact workspace name.

## Review an artifact

Before accepting or sharing an artifact, verify:

- title, owner, workspace, and intended audience;
- source conversation or coding task;
- current draft, immutable version, and live-version identity;
- data source, generated time, refresh model, and current freshness;
- validation, rendered smoke, and acceptance evidence;
- schedules and external connections;
- sharing mode and sensitive content; and
- rollback or prior live version.

Unsupported or binary files should provide safe download guidance. Raw payload
views can contain sensitive data; expand them only when necessary and do not
copy them into tickets or chat without redaction.

## Build and publish an artifact app

1. Create or update a private draft in the owning workspace.
2. Validate the manifest, source package, routes, and declared data/secret
   bindings.
3. Deploy the private draft through the trusted broker.
4. Run route, data, browser, and acceptance checks against that exact version.
5. Review the rendered draft and logs.
6. Promote the reviewed version through the operator UI.
7. Verify the live route and preserve the prior live version for rollback.

A source commit, successful build, deployed private draft, passing HTTP check,
or Storybook story is not proof of live promotion. A shared-platform deploy is
also distinct from customer-runtime rollout.

Hosted MCP server artifacts add a connection-review step after promotion. See
[Build a hosted MCP server](/docs/hosted-mcp-artifacts).

## Share safely

Use **People with access** for collaboration inside Topline:

- **Viewer** can open the shared artifact and, for artifact apps, review the
  current draft and immutable versions but cannot edit, publish, share, or
  schedule.
- **Editor** can use write-capable artifact controls, while owner-only sharing,
  workspace visibility, and deletion remain restricted.
- Direct workspace membership can grant corresponding workspace artifact
  access while membership remains active.

Use **General access** for delivery of an approved live artifact. A restricted
or public viewer token opens only the live version; it does not grant workspace
membership, draft review, immutable-version access, or editing.

Never use public access for tenant-private data, credentials, raw PII, or an
unreviewed draft.

## Manage assets

Uploads accept PNG, JPEG, WebP, GIF, PDF, plain text, Markdown, CSV, JSON,
DOCX, XLSX, and ZIP files. Images are limited to 10 MiB and 25 million pixels;
other files are limited to 25 MiB. Topline verifies the declared type against
the file content, so renaming an unsupported file does not make it uploadable.

In **Assets**:

1. choose **All assets**, **Unfiled**, or a folder;
2. search by file or folder name;
3. create a folder or upload approved files;
4. preview supported content and edit descriptive metadata;
5. copy the stable asset reference for another Topline workflow;
6. cut and paste an asset into another folder when reorganizing; and
7. download or delete only after checking active consumers.

A folder must be empty before deletion. Failed upload, move, metadata save, or
delete operations preserve the existing asset and show a recoverable error.
Brand logos and favicons can be selected from this library, but changing a
brand asset does not automatically update a separately deployed customer
runtime.

## Storyboard and feedback

Storyboard at `/storyboard` owns visual drafting and review. Keep the task in
its originating Storyboard conversation, inspect the rendered result and
validation, then publish only the approved draft. Restore the previous
published version when rollback is required.

Feedback at `/feedback` accepts a bounded bug, polish, or feature report and
optional images. It queues a coding task; it does not itself merge or deploy a
fix. Submit once, preserve the returned task, and answer its attention items
instead of creating duplicates.

## Automation and MCP

An artifact schedule repeats the saved refresh or supported run under its
existing authority. Confirm the target, timezone, cadence, next run, and last
outcome before enabling it. App-managed schedules are changed through the app
manifest rather than the generic schedule editor.

Build MCP supports private artifact build, inspection, validation, deployment,
logs, and handoff. Live promotion remains an operator action. Workspace MCP
exposes only permission-filtered context and reviewed knowledge operations.

## Errors and recovery

- **Artifact missing:** confirm tenant, workspace membership, direct share, and
  whether the requested state is draft, version, or live.
- **Draft deploy failed:** preserve the exact version and logs, fix the narrow
  source or configuration issue, then deploy a new reviewed version.
- **Live route failed:** restore the previous reviewed live version when safe
  and investigate without promoting an unchanged retry.
- **Move failed:** the item stays in its prior workspace and remains selected
  when recovery is possible.
- **Share failed:** do not assume partial access; reload the authoritative
  people and general-access state.
- **Asset upload failed:** keep the source file, verify it is one of the listed
  types and within the applicable byte and pixel limits, then retry only after
  the reported format, authorization, or storage issue is corrected.

## Enablement and smoke check

Use a non-sensitive test workspace and artifact:

1. create the workspace and one thread;
2. save and file an output;
3. upload and reference a small asset;
4. validate and deploy a private artifact draft;
5. verify a named viewer can read but not edit;
6. promote and verify the live viewer route separately;
7. archive and restore the workspace; and
8. verify permanent deletion remains blocked while dependencies exist.

## Current limitations

Supported renderers, artifact app runtimes, share modes, schedules, and MCP
connections vary by tenant and artifact kind. Public and embedded links expose
only live content. Deleting a workspace, artifact, asset, schedule, or
connection does not erase historical audit records.