> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> The nouns and lifecycle boundaries used throughout the platform.

These are the nouns used throughout the platform and these docs.

## Workspace

A workspace is the isolation boundary for a brand. It owns domains, competitors, prompts, jobs, reports, recommendations, members, credentials, billing state, chat threads, and page evaluations. A session can access only active memberships. A machine key is bound to one workspace.

## Run

A run is a measurement execution in the Python pipeline. It records the preset, date, provider responses, citations, extracted mentions, metrics, and cost. Pipeline outcomes can be <code>complete</code>, <code>partial</code>, or <code>failed</code>. The web job that launches it has its own <code>running</code>, <code>succeeded</code>, <code>failed</code>, or <code>cancelled</code> state.

## Prompt

A prompt is a tracked question sent to one or more answer engines. It has an intent, topic, language, importance, lifecycle state, and lineage. User-authored prompts are preserved by curation. Generated prompts must pass deterministic and model-assisted bias checks before activation.

## Signal

A signal is an observed input such as a GSC row, GA4 metric, authority measure, provider response, or crawler result. Signals retain their provider-local date and source identity. A score snapshot records exactly which rows and registry versions it used.

## Research artifact

A research artifact is a schema-validated, immutable output from one stage of a research run. It carries source references, timestamps, digests, and the operation that produced it. Only artifacts from completed runs can become the latest eligible evidence.

## Recommendation lifecycle

A recommendation is tracked work, not generated prose alone. Its canonical states are:

```text theme={null}
proposed -> todo -> in_review -> done -> archived
```

Transitions use optimistic concurrency and append-only evidence. Drafts and reviews are immutable records. See [Recommendations](/recommendations) for the complete transition matrix.

## Credit

A credit is one integer micro-USD unit. One US dollar equals 1,000,000 micro-USD. Positive ledger entries create expiring lots. Reservations hold portions of those lots before an operation begins.

## Operation

An operation is the metered envelope around work that can call a paid provider. It has an idempotency identity, reservation, signed token, active budget lease, cost events, sealed manifest, and settlement. A job must receive authorization before each provider call.

## Job, operation, and run

These records answer different questions:

| Record    | Purpose                                                            |
| --------- | ------------------------------------------------------------------ |
| Job       | What the web application launched and whether its process is alive |
| Operation | What was reserved, authorized, charged, and settled                |
| Run       | What measurement or research evidence the pipeline produced        |

One user action can create all three. Their identifiers are linked, but their states do not mean the same thing.

## Snapshot and digest

A snapshot freezes the inputs used for a score or report. A canonical digest is a stable hash over normalized input data and contract versions. Repeating a replay-safe build with the same inputs returns the existing result instead of creating a different record.