# Context Vault

Context vault is the planned workspace catalog for source materials that inform
agent work but should not be pasted directly into every prompt. It covers
documents, statements of work, PDFs, diagrams, images, audio/video recordings,
transcripts, and client reference artifacts.

The vault is related to context indexing and transcription, but it has a
different job: it records provenance, sensitivity, retention, ownership, and
safe consumption rules for project inputs.

## Goals

- Register source artifacts with stable metadata and checksums.
- Classify sensitivity before an artifact is used by an agent.
- Convert large or binary inputs into bounded summaries, excerpts, transcripts,
  or context packs.
- Preserve provenance so BA, PO, Architect, QA, and Release can cite which
  artifact informed a requirement, risk, decision, or validation result.
- Keep raw sensitive inputs out of runtime prompts unless policy explicitly
  allows a bounded excerpt.

## Artifact Metadata

Every vault artifact should record:

- artifact id and workspace or tenant id;
- original source, file name, media type, size, checksum, and registered time;
- owner role or user;
- sensitivity classification and retention policy;
- ingestion status, conversion status, redaction status, and error state;
- derived outputs such as Markdown conversion, transcript, summary, embeddings,
  or context-pack references.

## Consumption Model

Agents should not load raw vault artifacts by default. They should request a
bounded context pack or artifact summary scoped to the active task, role, phase,
and token budget.

The pack should include:

- artifact references and provenance links;
- selected excerpts with inclusion reasons;
- redaction decisions and omitted-sensitive-data notes;
- budget summary and truncation indicators;
- stale or failed-ingestion warnings.

## Security And Privacy

Vault ingestion must be tenant-aware and fail closed when classification or
redaction is uncertain. Secrets, credentials, health data, payment data, and
other regulated content require explicit policy handling before they can be
summarized or exposed to a runtime.

External conversion or transcription providers are opt-in. Local conversion and
local transcription should be preferred when a workspace or tenant requires
offline handling.

## Implemented Local Surface

The first local slice stores catalog metadata in
`.agent-workflow/context-vault/artifacts.json` and exposes the same domain
services to CLI and web read APIs.

```bash
orchestra context-vault add \
  --path docs/sow.md \
  --source "Client SOW" \
  --type document \
  --owner business_analyst \
  --tenant tenant-a \
  --workspace payments \
  --sensitivity confidential \
  --retention 7y

orchestra context-vault list --tenant tenant-a --workspace payments --json
orchestra context-vault show --id vault-abc123 --json
orchestra context-vault pack --query "payment constraints" --task STORY-001 --json
```

The catalog records source, type, owner, tenant, workspace, sensitivity,
retention, checksum, ingestion status, and optional transcript path. `list`
supports pagination and filters for tenant, workspace, type, sensitivity, and
status. The web console can read the same catalog through `/api/context-vault`.

`context-vault pack` creates bounded JSON and Markdown artifacts under
`.agent-workflow/context-packs/`. It reads text artifacts or transcript outputs,
redacts secret-like values and common PII such as emails and phone numbers, and
does not require agents to load raw registered files directly.

Future ingestion workers can add conversion, transcription, classification,
embeddings, and status transitions without changing the catalog read API.

The web console can later expose this as a catalog view, but it should consume
the same domain services as the CLI/API.

## Related Work

- GitHub issue `#449`: context vault epic.
- GitHub issue `#367`: audio and video transcription evidence skill.
- GitHub issues `#423` through `#427`: context index, search, bounded context
  packs, redaction, and runtime prompt integration.