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

# Artifacts

> OrgX artifacts are verified agent outputs — specs, PRDs, campaigns, reports — with citations, reasoning chains, and verifier proof attached. Artifacts persist in org memory and can be referenced by any agent or human across sessions.

**Artifacts** are the tangible outputs of agent work. Every time an agent completes a task, the result is captured as an artifact with full provenance, citations, and verification.

## Artifact Types

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines">
    Product requirements, technical designs, feature briefs
  </Card>

  <Card title="Code" icon="code">
    Pull requests, patches, migrations, tests
  </Card>

  <Card title="Content" icon="pen">
    Blog posts, email sequences, social copy, landing pages
  </Card>

  <Card title="Reports" icon="chart-line">
    Research findings, competitive analysis, market trends
  </Card>

  <Card title="Briefs" icon="clipboard">
    Campaign briefs, design rationale, meeting prep
  </Card>

  <Card title="Sequences" icon="envelope">
    Sales outreach, nurture campaigns, follow-up emails
  </Card>
</CardGroup>

***

## Artifact Lifecycle

Every artifact moves through defined states:

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> Forming: Agent starts work
    Forming --> Testing: Draft complete
    Testing --> Ready: Verification passed
    Testing --> NeedsYou: Verification failed
    NeedsYou --> Testing: Human fixes/feedback
    Ready --> Shipped: Approved
    Ready --> Degraded: Issues detected post-approval
    Shipped --> [*]
    Degraded --> Testing: Remediation
```

### States

| State        | Description                            | Actions Available            |
| ------------ | -------------------------------------- | ---------------------------- |
| **Forming**  | Agent actively working                 | View progress, cancel        |
| **Testing**  | Running verification checks            | Wait for results             |
| **Ready**    | Passed verification, awaiting approval | Approve, reject, edit        |
| **NeedsYou** | Verification failed, needs human input | Fix issues, provide feedback |
| **Shipped**  | Approved and deployed/published        | View, archive                |
| **Degraded** | Issues found after shipping            | Remediate, rollback          |
| **Dormant**  | Archived or superseded                 | Reference only               |

***

## Artifact Structure

Each artifact contains:

```typescript theme={"dark"}
interface OrgArtifact {
  id: string;
  type: 'spec' | 'pr' | 'content' | 'report' | 'brief' | 'sequence';
  title: string;
  content: string | Record<string, unknown>;

  // Provenance
  agent_instance_id: string;
  workflow_id: string;
  initiative_id: string;
  work_item_id: string;

  // Verification
  verification_status: 'pending' | 'passed' | 'failed';
  verification_proof: VerificationProof;

  // Evidence
  citations: Citation[];
  evidence_ids: string[];

  // Lifecycle
  state: ArtifactState;
  created_at: string;
  updated_at: string;
  shipped_at?: string;

  // Metadata
  schema_version: string;
  tags: string[];
}
```

### Citations

Every artifact includes source citations:

```typescript theme={"dark"}
interface Citation {
  id: string;
  source_type:
    | 'linear_issue'
    | 'github_pr'
    | 'document'
    | 'url'
    | 'agent_output';
  source_id: string;
  source_url?: string;
  excerpt?: string;
  confidence: number; // 0-1
}
```

Example citations in an artifact:

```json theme={"dark"}
{
  "citations": [
    {
      "source_type": "linear_issue",
      "source_id": "ENG-123",
      "source_url": "https://linear.app/acme/issue/ENG-123",
      "excerpt": "User reported infinite loop when clicking login",
      "confidence": 0.95
    },
    {
      "source_type": "github_pr",
      "source_id": "45",
      "source_url": "https://github.com/acme/app/pull/45",
      "excerpt": "Previous auth fix that may be related",
      "confidence": 0.72
    }
  ]
}
```

***

## Verification

Before an artifact can ship, it passes through the **Verifier**:

```mermaid theme={"dark"}
flowchart LR
    A[Artifact Draft] --> B{Citation Check}
    B -->|Pass| C{Policy Check}
    B -->|Fail| G[Needs Human Input]
    C -->|Pass| D{Contract Check}
    C -->|Fail| G
    D -->|Pass| E{Budget Check}
    D -->|Fail| G
    E -->|Pass| F[Ready to Ship]
    E -->|Fail| G
```

### Verification Checks

<AccordionGroup>
  <Accordion title="Citation Check" icon="quote-right">
    **What it verifies**: Sources are referenced and accessible

    * Minimum 3 citations for most artifact types
    * All URLs resolve and return expected content
    * Citations support the claims made in the artifact

    **Failure action**: Surface for human to add citations or verify claims
  </Accordion>

  <Accordion title="Policy Check" icon="shield">
    **What it verifies**: Content complies with policies

    * Brand tone and style guidelines
    * Legal compliance (no false claims)
    * Security best practices (no exposed secrets)
    * Accessibility standards where applicable

    **Failure action**: Highlight violations for human review
  </Accordion>

  <Accordion title="Contract Check" icon="file-contract">
    **What it verifies**: Output matches expected schema

    * Required fields present
    * Data types correct
    * Format matches workflow spec

    **Failure action**: Agent retries or escalates to human
  </Accordion>

  <Accordion title="Budget Check" icon="coins">
    **What it verifies**: Execution stayed within limits

    * Token usage within p95 budget
    * Latency within p95 budget
    * No runaway tool calls

    **Failure action**: Flag for ops review, may still ship
  </Accordion>
</AccordionGroup>

### Verification Proof

Successful verification generates a proof:

```typescript theme={"dark"}
interface VerificationProof {
  id: string;
  artifact_id: string;
  checks: {
    citation: { passed: boolean; score: number; details: string };
    policy: { passed: boolean; violations: string[] };
    contract: { passed: boolean; schema_version: string };
    budget: { passed: boolean; tokens_used: number; latency_ms: number };
  };
  overall_verdict: 'passed' | 'failed' | 'warning';
  verified_at: string;
  verifier_version: string;
}
```

***

## Artifact Schemas

Different artifact types have specific schemas:

### Spec Artifact

```typescript theme={"dark"}
interface SpecArtifact {
  type: 'spec';
  content: {
    overview: string;
    requirements: Requirement[];
    acceptance_criteria: string[];
    technical_notes?: string;
    open_questions?: string[];
  };
}

interface Requirement {
  id: string;
  description: string;
  priority: 'must' | 'should' | 'could';
  rationale?: string;
}
```

### PR Artifact

```typescript theme={"dark"}
interface PRArtifact {
  type: 'pr';
  content: {
    title: string;
    description: string;
    branch: string;
    base: string;
    files_changed: FileChange[];
    tests_added: string[];
    review_notes: string;
  };
  github_pr_url?: string;
  linear_issue_id?: string;
}
```

### Campaign Brief Artifact

```typescript theme={"dark"}
interface CampaignBriefArtifact {
  type: 'brief';
  content: {
    objective: string;
    target_audience: string;
    key_messages: string[];
    channels: Channel[];
    timeline: TimelineItem[];
    success_metrics: Metric[];
    budget_estimate?: number;
  };
}
```

***

## Working with Artifacts

### Viewing Artifacts

Artifacts appear in several places:

1. **Mission Control**: Recent artifacts in the activity feed
2. **Initiative Detail**: Artifacts linked to the initiative
3. **Decision Review**: Artifact preview when approving
4. **Task Detail**: Artifacts produced for the task

### Editing Before Ship

While in `Ready` state, you can edit artifacts:

1. Open the artifact detail view
2. Click **Edit** to modify content
3. Changes are tracked in version history
4. Re-run verification if needed
5. Approve the edited version

### Exporting Artifacts

Export formats available:

| Format   | Use Case                |
| -------- | ----------------------- |
| Markdown | Documentation, GitHub   |
| PDF      | Stakeholder sharing     |
| JSON     | API integration         |
| Notion   | Push to Notion database |

***

## Artifact Evidence

Each artifact links to its **evidence chain**:

```mermaid theme={"dark"}
flowchart TB
    A[Artifact] --> B[Agent Instance]
    A --> C[Citations]
    A --> D[Tool Calls]
    A --> E[Verification Proof]

    B --> F[Work Item]
    B --> G[Prompt Stack]
    B --> H[Telemetry]

    C --> I[Source Documents]
    C --> J[Linear Issues]
    C --> K[GitHub PRs]

    D --> L[Tool Inputs]
    D --> M[Tool Outputs]
```

This evidence chain enables:

* **Audit**: Trace how any artifact was produced
* **Debug**: Understand why verification failed
* **Improve**: Learn from successful patterns

***

## Best Practices

<AccordionGroup>
  <Accordion title="Review Citations">
    Always check that citations support the artifact's claims. Agents sometimes
    hallucinate connections—verification catches most, but human review catches
    all.
  </Accordion>

  {' '}

  <Accordion title="Use Edit Sparingly">
    If you frequently edit artifacts before shipping, consider adjusting agent
    prompts or providing better context in tasks. Artifacts should be close to
    shippable on first pass.
  </Accordion>

  {' '}

  <Accordion title="Track Verification Trends">
    If verification failures spike, investigate: - Are task descriptions unclear?

    * Do agents need different tools? - Are policies too strict?
  </Accordion>

  <Accordion title="Archive Don't Delete">
    Move artifacts to `Dormant` instead of deleting. The evidence chain is
    valuable for learning and compliance.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Decisions" icon="check-circle" href="/docs/platform/decisions">
    Learn about the approval workflow for artifacts.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/docs/platform/architecture">
    Understand how artifacts fit in the system.
  </Card>
</CardGroup>