Viewport Docs

The two YAML schemas your team commits. Workspace config and workflow definitions.

Viewport reads two YAML files from your repo:

.viewport/config.yaml: the workspace contract. Names the workspace, declares context providers, registers workflows.
.viewport/workflows/NAME.yaml: one file per workflow.

Both validate against JSON Schemas committed in the OSS daemon repo. The canonical sources are below; the live schemas are the source of truth.

`.viewport/config.yaml`: workspace contract

Schema: viewport/packages/daemon/schemas/viewport-config-v1.schema.json (209 lines, JSON Schema draft-07).

Top-level shape:

version: 1
name: acme-api                   # workspace name

resources:
  contexts:                      # resource refs (vaults, etc.)
    - ref: ctx_acme_runbooks
  workflows:
    - ref: review
  plans: []
  agentProfiles: []

context:
  providers:
    - id: repo_docs
      provider: repo-docs
      paths: ['CLAUDE.md', 'AGENTS.md', 'docs/**/*.md']
    - id: team_memory
      provider: viewport-vault
      vault: ctx_acme_runbooks
      capabilities: [search, get, propose]
      privacy: control_plane_blind
  resolution:
    order: [repo_docs, team_memory]
    propose_fallback_provider: team_memory

workflows:
  review:
    path: .viewport/workflows/review.yaml

approvals:
  risky_paths:
    - paths: ['apps/api/src/middleware/**']
      mode: ask                  # ask | allow | deny

defaults:
  inboxRoute: team_platform
  workflow: review
  visibility: team               # private | team | organization
  context_candidate_review: single_reviewer

scope:
  includeChildren: true
  maxDepth: 5                    # capped at 5
  exclude: ['vendor/**', 'node_modules/**']

Notes:

additionalProperties: true at the root, so the schema is forward-compatible: you can stash future fields without breaking old daemons.
Provider types in context.providers[] are open-ended. Built-in: repo-docs, viewport-vault. Custom providers can be added via the workflow plugin SDK.
Validate locally: vpd validate or vpd contract resolve.

`.viewport/workflows/NAME.yaml`: workflow definition

Schema: viewport/packages/daemon/schemas/workflow-v1.schema.json (245 lines).

Top-level shape:

schema: viewport.workflow/v1
name: review-auth-change
title: Review auth middleware change
description: Plan-first auth refactor with reviewer sign-off.

inputs:
  branch:
    type: string
    description: Branch to operate on
  paths:
    type: json

context:
  - ctx_acme_runbooks            # vault attachments

requires:
  agents: [claude-code]
  tools: []
  integrations: []
  secrets: []

nodes:
  inspect:
    type: read_only

  plan:
    type: plan
    review:
      required: true
      reviewers: team_platform   # share group or role

  execute:
    type: apply_plan
    gate:
      destructive: ask           # ask | allow | deny

  capture:
    type: capture_outputs

Input / output types

inputs[*].type accepts: string | number | boolean | json.

Node types

The built-in node types are inferred from daemon code (packages/daemon/src/workflows/). Custom node types come from plugins.

`type`	Behavior
`read_only`	Inspect the repo. No file writes, no shell.
`plan`	Produce a plan artifact. Optionally gated on review.
`apply_plan`	Execute an approved plan. Per-action gates apply.
`shell`	Run a specific command. Allow-listed.
`capture_outputs`	Persist run artifacts.

Plugin-defined types use a contract: viewport.workflow-plugin/v1 declaration in the SDK (see Workflows).

Context Vault schemas

These are not workspace-level. They are the internal data formats the encrypted log uses on the wire. Worth knowing if you're auditing crypto.

Under viewport/packages/context-engine/schemas/:

context_event_v1.schema.json: one event in the log
context_profile_v1.schema.json: vault profile and settings
context_bundle_manifest_v1.schema.json: manifest of bundled entries
context_erase_receipt_v1.schema.json: proof of erasure
context_key_grant_v1.schema.json: recipient grants
context_key_grant_hpke_draft_01.schema.json: HPKE-wrapped grants

version: 1 (and schema: viewport.workflow/v1) are stable. Future version bumps will ship with a migration command and a deprecation window. The daemon accepts both versions for at least one minor release cycle.

Validation in CI

# fails non-zero on schema violations
vpd validate
vpd workflow validate .viewport/workflows/review.yaml

Drop these into your pre-commit and CI.

PlannedA separately published `@viewportai/workspace-schema` npm package is on the roadmap but not shipped. For now, the schemas live in the daemon repo. Generators that need the schema can fetch the raw JSON files from `viewport/packages/daemon/schemas/` until that lands.

Concepts: Workflows for what the schema means semantically
CLI: workflow for vpd workflow validate and friends
API for the runtime workflow-run WebSocket message that wraps these YAMLs

Workflow YAML