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

# Portfolio Intake Workflow

> The first-run guide for communications intake, TattooAPI, private staging, private worker review, approved storage, and runtime promotion.

# Portfolio Intake Workflow

Portfolio intake turns artist conversations and media into review-ready evidence. It does not turn text messages into public portfolio updates automatically.
The workflow keeps private media staging separate from governed upload completion and human review.

## Flow

```text theme={"dark"}
Message or call
  -> Permanent resolves existing artist identity evidence
  -> TattooAPI queues operator review when no artist is safely resolved
  -> WorkOS-scoped private media submission
  -> private R2 media staging
  -> TattooAPI upload integrity completion
  -> private worker review evidence
  -> mapped super-admin or operator review
  -> private Sanity draft (`promoted_to_sanity`)
  -> separate runtime and distribution review
  -> public Convex projection only after governed promotion
```

## What Each System Does

| System                      | Job                                                                                                      | Authority                       |
| --------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------- |
| Communications buffer       | Inbox context                                                                                            | Evidence source only            |
| TattooAPI                   | Policy, auth, review, identity evidence, projection, and write boundary                                  | Governing authority             |
| Private media staging       | Private temporary media staging                                                                          | Evidence storage only           |
| Upload integrity completion | Verify private object bytes, size, image signature, MIME metadata, and server-side SHA-256 before review | Staging state transition only   |
| Private workers             | Outbound private compute for classification and context loading                                          | Review evidence only            |
| Approved portfolio storage  | Approved portfolio/media lake                                                                            | Storage after review            |
| TattooAPI runtime           | Runtime mappings and canonical promotion state                                                           | Runtime truth after approval    |
| Observability               | Metadata-first observability                                                                             | Trace only, not write authority |

## Identity Evidence, Not KYC

TattooAPI v0 uses identity evidence to help reviewers connect inbound media to artists or studios. It is not legal KYC.

| Status                 | Meaning                                                              |
| ---------------------- | -------------------------------------------------------------------- |
| `unmatched`            | No reliable contact or profile evidence matched.                     |
| `phone_matched`        | A normalized phone hash or contact record matched existing evidence. |
| `review_required`      | Evidence is incomplete, ambiguous, or conflicting.                   |
| `verified_by_operator` | A human operator approved the evidence for this workflow.            |

Do not claim `kyc_verified` in v0. Legal identity verification would require a separate approved provider and policy.

## Launch Caveat

Communications API access and TattooAPI readiness do not equal SMS/MMS launch readiness. A2P approval remains required before artist-facing SMS/MMS intake is production-ready.

## Worker Boundary

Private workers authenticate portfolio creation and upload completion with a WorkOS organization API key in `X-API-Key`. The operator-context capability-claims route uses a separate short-lived WorkOS client-credentials Bearer token. These credentials are not interchangeable.

Workers can request context and return evidence, but they cannot:

* write directly to approved portfolio storage
* mutate runtime records directly
* publish public surfaces
* send messages without approval
* store raw phone numbers, media URLs, provider tokens, or API keys in traces

Use [Portfolio Intake](/guides/portfolio-intake) for the staging envelope and classification contract.

## Permanent Integration

Permanent uses a dedicated Production WorkOS organization API key with exactly `artists:read` and `portfolio_intake:stage` for artist evidence reads, portfolio submission creation, and bodyless upload completion. TattooAPI maps the non-secret key ID to an approved service actor in Convex.

The service mapping carries `portfolio_intake:stage_cross_tenant` for governed artist identity resolution and staging across approved tenants. That internal TattooAPI capability is not a WorkOS key permission. Permanent cannot approve its own submission, promote canonical runtime truth, call Sanity directly, or publish a public surface.

Upload completion itself can only move verified media from `awaiting_upload` to `awaiting_review`; it cannot approve, resolve or reassign an artist, call Sanity, activate a public surface, or promote canonical runtime state. Unresolved attribution stays review-required and fail-closed with `portfolioStagingAllowed=false`. Identity resolution requests use the separate `POST /api/private/portfolio-intake/v1/artist-resolution-requests` review lane; upload completion adds no artist-resolution route.

Permanent polls `GET /api/private/portfolio-intake/v1/submissions/{submissionId}` after upload verification. The bounded response exposes workflow status without exposing the private object pointer, raw review notes, or actor-mapping details.

A mapped human operator uses a WorkOS AuthKit bearer session with `portfolio_intake:review` to call the approval route. A successful approval writes a private `tattooPortfolioAsset` draft to Sanity and marks the intake `promoted_to_sanity`. It does not make the asset public. Public reads require a later governed Convex projection with `published_public` and distribution approval.

See the endpoint contracts under [Portfolio Intake API](/api-reference/portfolio-intake/create-submission).