# Topline Product Guide

This guide explains how customers use Topline day to day. It is organized by
jobs operators perform rather than by implementation package.

## Product model

Topline combines conversation, data, automation, generated applications, and
delegated coding work inside one tenant-scoped workspace.

The major objects are:

- **Projects** group related chats, instructions, artifacts, skills, and data
  scope.
- **Chats** are the operator's working conversations with Topline.
- **Sources** connect external systems and expose approved resources.
- **Pipelines** ingest or refresh source data.
- **Automations** run schedules and reminders.
- **Artifacts** are saved outputs such as documents, reports, dashboards, and
  hosted artifact apps.
- **Coding tasks** delegate repository or artifact implementation to a bounded
  workforce runtime.
- **Memory and glossary** preserve approved preferences and company language.
- **Scopes** control who can view or change shared resources.

## Access and permissions

Topline hides unavailable actions in the interface and enforces permission
again at the API. Common capabilities include chat, sources, browser control,
workforce, memory, glossary, token management, billing, and tenant
administration.

If an expected feature is missing:

1. confirm the operator is in the intended tenant;
2. confirm the account and product profile are active;
3. ask an administrator to verify the required capability; and
4. refresh the application after the grant changes.

Do not share another user's link or token to work around a missing capability.

## Start with a project

Use a project when work will span multiple conversations, data sources, or
deliverables.

1. Open **Workspace > Projects**.
2. Create a project with a name that describes the business outcome.
3. Set project instructions for durable constraints and definitions.
4. Attach or create chats for separate workstreams.
5. Add only the data scope and skills required by the project.

Project instructions should contain stable guidance. Put temporary requests in
chat and company-wide terminology in the glossary.

## Work in chat

Chats are the main operator entry point.

### Ask for analysis or an answer

Describe the outcome, relevant customer or business scope, time range, and
required format. Topline may use approved sources, memory, glossary, artifacts,
or workforce tools depending on the request and permissions.

### Attach files

Attach supporting files when they are the authoritative input. Do not upload
secret files, raw credential exports, or unnecessary PII. Large or reusable
files should be saved in the appropriate asset or source workflow instead of
repeatedly attached to chats.

### Save an output

Save durable work as an artifact. Give it a descriptive name, verify its scope,
and review the rendered output before sharing or publishing.

### Archive and restore

Archive completed chats to reduce clutter. Archiving does not erase audit
history or automatically delete attached artifacts and tasks.

## Use the secure browser

The secure browser is an isolated AWS AgentCore browser for human sign-in and
approved browser assistance. Open it from the monitor button in an eligible
chat, select or create a profile, and optionally provide a starting URL.

Enter passwords, MFA, payment details, CAPTCHAs, and recovery values yourself
through the secure-browser page. Never paste them into chat. See **Secure
Browser** for profiles, controls, agent approvals, security, and errors.

## Connect data sources

Open **Account > Sources** to configure and operate customer data connections.

The normal lifecycle is:

1. create or select the connection;
2. store credentials through the credential workflow;
3. verify identity and authorization;
4. discover available resources;
5. select only required resources;
6. run a bounded sample or schema inspection;
7. configure ingestion or refresh behavior;
8. verify the first successful run; and
9. monitor freshness and failures.

Source credentials are secret references. They must not appear in chat,
artifact code, generated documentation, logs, or committed configuration.

### Resource schemas

Review field meaning, data classification, retention, and identifiers before
building reports. Do not infer business meaning from a column name when a
connector reference or glossary definition is available.

### Pipeline failures

Start with the latest run, error category, and last successful refresh. Retry
only after addressing authentication, schema, throttling, or configuration
errors. Repeated blind retries can increase provider load and obscure the
original failure.

## Build and operate automations

Automations contains schedules and reminders.

### Schedules

Schedules run supported recurring work such as artifact refresh. Review the
timezone, cadence, target, enabled state, and recent runs before saving.

Disable a schedule when investigating repeated failures. Re-enable it only
after a manual or smoke run verifies recovery.

### Reminders

Reminders return an operator task at the requested time. Use them for human
follow-up, not for unattended production work that needs retries, idempotency,
or operational monitoring.

## Work with artifacts and artifact apps

Artifacts are durable outputs owned by a tenant and scope.

### Review an artifact

Check title, source, content, sharing, scope, versions, and acceptance evidence.
For data-backed output, verify the refresh model and whether the displayed data
is live, scheduled, or a bounded snapshot.

### Artifact-app lifecycle

1. Create or update a private draft.
2. Validate the manifest and package.
3. Deploy through the trusted broker.
4. Run route, data, browser, and acceptance checks.
5. Review draft content and logs.
6. Promote through the operator UI.
7. Monitor the live version and keep rollback evidence.

External MCP can create, deploy, inspect, and open private drafts within its
granted scopes. Live promotion remains an operator-controlled UI action.

### Sharing and publishing

Before sharing, confirm the audience, scope, data sensitivity, live refresh
behavior, and expiration expectations. Public routes must never expose
credentials or tenant-private data.

## Delegate coding work

Use a coding task for repository changes, hosted applications, substantial UI
work, or implementation that requires checks and source edits.

Provide:

- goal and target user;
- acceptance criteria;
- constraints and non-goals;
- relevant data or integration context;
- expected validation; and
- whether deployment or promotion is explicitly authorized.

The task-scoped workforce bridge lets the coding agent read instructions, use
approved platform tools, ask for operator input, report progress, and return
validation evidence. It does not grant general production or database access.

Review changed files, checks, remaining risks, and deployment requirements
before accepting the result.

## Manage memory, preferences, and glossary

Use preferences for explicit guidance about how Topline should respond or
operate for an authorized user. Use the glossary for company terms,
abbreviations, and definitions that should be resolved consistently.

Prefer a concise, testable statement. Do not store passwords, tokens, customer
rows, or transient task instructions in memory or glossary entries.

When a proposed memory conflicts with an existing entry, resolve the conflict
instead of silently creating competing rules.

## Developer Access and MCP

Open **Account > Developer Access** to connect Codex, Claude Code, or a custom
MCP client.

Choose the product that matches the job:

- **Build artifacts** installs Topline Build MCP for artifact apps, deployment
  status, offline package inspection, logs, Storybook access, and handoff links.
- **Use workspace context** installs Topline Workspace MCP for documentation,
  workspace discovery, accessible conversations, approved preferences,
  permission-filtered context, glossary terms, and reviewed company knowledge.

Install both when the assistant needs both capabilities. Each product has an
independent setup snippet and OAuth audience; the legacy combined Harness MCP
is retained only for existing integrations.

Each product card shows active OAuth permissions and the last successful call.
**Check connection** refreshes that Topline-side status; it cannot inspect
whether the setup has been installed in the external client.

The recommended path is OAuth with PKCE. Manual connector tokens are a fallback
for environments that cannot complete OAuth. Grant the narrowest scopes,
choose a bounded lifetime, store the token in a secret manager, and revoke it
when no longer needed.

Use the documentation tools before guessing tool behavior:

- `platform_search_documentation` searches product and API documentation.
- `platform_read_documentation` reads a complete result.

See **External API Guide**, **MCP Server Reference**, and the generated MCP tool
reference for integration details.

## Tenant administration

Administrators manage members, access rules, credentials, audit history,
billing, sources, skills, coding agents, Storyboard, and product settings.

### Members and scopes

Grant access through roles, capabilities, product profiles, and resource scope.
Remove access promptly when responsibilities change. Verify both the identity
record and resource memberships during offboarding.

### Credentials

Create named secret references with a clear owner and purpose. Rotate through
the supported workflow, verify consumers, promote the new version, and revoke
the old value. Topline should display metadata and health, never the stored
secret value after creation.

### Audit investigation

Search by actor, action, resource, outcome, and time range. Start narrow, then
expand. Preserve relevant IDs and timestamps without copying sensitive payloads
into tickets or chat.

### Billing and usage

Use current-period usage for operational monitoring and exports for analysis.
Provider billing delays and attribution rules can make very recent totals
provisional.

## Troubleshooting sequence

For most product problems:

1. capture the visible error and the action that produced it;
2. confirm tenant, user, capability, and resource scope;
3. check whether the feature backend is configured;
4. inspect the most specific status, run, or audit record;
5. retry only when the error is retryable or its cause is fixed; and
6. escalate with IDs, timestamps, environment, and bounded redacted evidence.

Do not include passwords, tokens, cookies, typed browser values, raw PII, or
unredacted provider payloads in support evidence.