Skip to content

Edition Feature Matrix

SkillMeat offers two editions optimized for different deployment scenarios: Local for personal use and single-user deployments, and Enterprise for multi-tenant installations. This comprehensive reference document explains the differences, feature availability, and configuration options for each edition.

Quick Reference: Which Edition Do I Need?

Scenario Edition Why
Personal artifact collection, local development Local Zero-config auth, SQLite, filesystem-native
Single-user production deployment Local Simpler operations, no external database
Multiple users, teams, organizational deployment Enterprise Multi-tenant support via role-based access control (RBAC)
Strict data isolation requirements Enterprise Tenant-scoped row-level security (RLS) on all tables
High-volume artifact management Enterprise PostgreSQL scalability and full-text search

Edition Overview

Local Edition

The Local edition is optimized for personal use, local development, and single-user deployments. It uses SQLite for data storage and the filesystem as the primary source of truth for artifacts.

Configuration: - Set SKILLMEAT_EDITION=local (default) - No additional environment variables required - SQLite database created automatically in user's collection directory

Authentication: - Defaults to LocalAuthProvider (zero-config) - Every request receives local_admin identity with full permissions - Optional: Enable basic local auth for credential enforcement

Enterprise Edition

The Enterprise edition supports multi-tenant deployments with PostgreSQL, enabling multiple organizations or teams to use the same deployment while maintaining strict data isolation.

Configuration: - Set SKILLMEAT_EDITION=enterprise - Requires DATABASE_URL pointing to PostgreSQL instance - Supports both LocalAuthProvider and Clerk for authentication

Authentication: - LocalAuthProvider: Basic credential-based auth - Clerk: JWT-based SSO integration for enterprise deployments - Enterprise PAT: Separate bootstrap auth for service clients

Edition Comparison

Aspect Local Enterprise
Database SQLite PostgreSQL
Multi-tenant support No Yes (row-level security)
Primary source of truth Filesystem Database cache
Default authentication LocalAuthProvider (zero-config) LocalAuthProvider or Clerk
Primary key type Integer UUID
ORM style SQLAlchemy 1.x query() SQLAlchemy 2.x select()
Artifact storage Filesystem (CollectionManager) Database + optional filesystem sync
Export capability Full TOML/JSON export Database-backed, limited export
Rate limiting Optional Supported
Full-text search Not supported Supported (PostgreSQL tsvector)

Feature Availability Matrix

This table shows which features are available in each edition and which require feature flags to enable.

Feature Local Enterprise Feature Flag Notes
Core Artifact Management
Collection CRUD Yes Yes — Different repository implementations per edition
Artifact creation Yes Yes —
Artifact uploads Yes No — Filesystem writes only in Local
Artifact deletion Yes No — Filesystem deletion only in Local
File content CRUD Yes Yes — Local uses filesystem; Enterprise uses CAS blob storage
Artifact metadata editing Yes Yes —
Artifact versioning Yes Yes —
Version History
Version history timeline Yes Yes version_history_ui_enabled (enabled) Chronological view of all versions
Version diff (any two versions) Yes Yes version_history_ui_enabled (enabled) Compare arbitrary version pairs
Restore by hash Yes Yes version_history_ui_enabled (enabled) Restore artifact to any prior version
Per-user version scoping No Yes — Enterprise-only: filter by user
Per-team version scoping No Yes — Enterprise-only: filter by team
Promotion workflow (user→team→enterprise) No Yes — Enterprise-only: approval chain
Divergence monitoring No Yes — Enterprise-only: detect source conflicts
Admin force-sync No Yes — Enterprise-only: override conflicts
Bulk admin version actions No Yes — Enterprise-only: batch restore/purge
Branching & DVCS
Branch creation & management Yes Yes dvcs_branching_enabled (disabled) Create, list, delete artifact branches
Branch-aware version history Yes Yes dvcs_branching_enabled (disabled) Version history scoped by branch
Branch merging & conflict resolution Yes Yes dvcs_branching_enabled (disabled) Merge branches with conflict detection
Protected branches & RBAC Yes Yes dvcs_branching_enabled (disabled) Enterprise: mutation authority enforced via VGS; _check_branch_protection is first action in all adapter mutation methods; scaffold/ops callers bypass via actor.system_role allowlist; unauthorized mutations return 403
Branch archival & cleanup Yes Yes dvcs_branching_enabled (disabled) Archive or delete inactive branches
Discovery & Population
Auto-discovery Yes Yes enable_auto_discovery (enabled) Scans filesystem or DB for artifacts
Auto-population (GitHub metadata) Yes Yes enable_auto_population (enabled) Fetches metadata from GitHub
Composite Artifacts
Composite artifact detection Yes Yes composite_artifacts_enabled (enabled) Recognizes multi-file artifact patterns
Composite artifact CRUD Yes Yes composite_artifacts_enabled (enabled)
Deployment & Projects
Projects Yes Yes — .claude/ directories in Local; DB scoped in Enterprise
Deployment profiles Yes Yes —
Deployment scoping (project isolation) Yes Yes — Enterprise: list_deployments scopes to resolved project_id only; path resolution failure returns empty set, not all rows
Project starters — durable registration Yes Yes — Enterprise: starters registered via EnterpriseDeploymentRepository.deploy() per (starter, profile) pair; deployment_id and version_id FK populated; persists across daemon restarts
Deployment profile selection Yes Yes — Canonical consumer: DeployProfileSelector with three modes — profile list (deployment_profile_ids[]), project defaults (use_project_defaults), all profiles (all_profiles)
CLI undeploy project scoping Yes Yes — Enterprise: CLI resolves project_path → project_id before API payload construction; 422 on unresolved path is surfaced to user
Deployment sets Yes Yes deployment_sets_enabled (enabled)
Git Connections
Git connection CRUD Yes Yes — Create, edit, delete repository connections
Multi-project linking Yes Yes — Link one connection to multiple projects
Git Sources tab on projects Yes Yes — View and manage linked connections per project
Connection filtering (project, unlinked) Yes Yes — Filter connections list by project or unlinked status
Team-scoped connection filtering No Yes — Filter connections by team
Layered token management No Yes — Per-connection, per-developer, and org-level tokens
Token Management panel No Yes — Enterprise UI for managing credential hierarchy
Scan configuration Yes Yes — Branch override and artifact type filters
Organization
Tags Yes Yes —
Groups Yes Yes —
Content Organization
Context entities Yes Yes —
Context modules Yes Yes —
Project templates Yes Yes —
ARC Integration
Reviewer Role artifact type Yes Yes — Tier-1 type; content-addressed; supports Ed25519 attestation
Council artifact type Yes Yes — Tier-2 type; content-addressed; supports run certification via ArtifactSignature
Raw artifact download endpoint Yes Yes — GET /api/v1/artifacts/{id}/download returns raw bytes
Content hash in list responses Yes Yes — Artifact list includes content_hash per item
Bearer token authentication Yes Yes — Authorization: Bearer support alongside X-API-Key
Hash-only verification Yes Yes — Lightweight verify without Ed25519 keys
Publishing & Marketplace
Marketplace publishing Yes Yes —
Marketplace consumption Yes Yes —
Source exclusions Yes Yes — Marketplace filtering
Advanced Features
Bundle authoring Yes Yes bundle_authoring_enabled (enabled) Bundle entity CRUD
Memory & context system Yes Yes memory_context_enabled (enabled) Captures learnings and decisions
Workflow engine Yes Yes workflow_engine_enabled (enabled) SWDL parsing and execution
Workflow-artifact sync Yes Yes workflow_artifact_sync_enabled (enabled) Keeps workflows in sync with artifacts
MCP & Sync
MCP management Yes No — Filesystem-only MCP operations
Sync management Yes No — SyncManager not available in Enterprise
Sync status & diffing Yes Yes — Different implementation per edition; Enterprise: sync_deployment_cache() resolves public_profile_id to stable IDs (resolution failure skips row rather than overwriting with null-profile)
Analytics & Observability
SAM telemetry ingestion Yes* Yes* sam_telemetry_ingestion_enabled (disabled) *Requires PostgreSQL telemetry models; off by default
Backstage analytics widgets Yes* Yes* — *Depends on telemetry data availability
Planned Features
SkillBOM generation No No skillbom_enabled (disabled) Roadmap
Modular content architecture No No modular_content_architecture (disabled) Roadmap
IDP bundle resolution No No idp_bundle_resolution_enabled (disabled) Planned
IDP drift detection No No idp_drift_detection_enabled (disabled) Planned
IDP content drift tracking No No idp_content_drift_enabled (disabled) Planned
Memory auto-extraction No No memory_auto_extract (disabled) Planned
Enterprise-only Features
Full-text search No Yes — PostgreSQL tsvector indexes
Row-level security (RLS) No Yes — Multi-tenant isolation
Advanced RBAC No Yes* — *Planned enhancement
Instance import policies No Yes — Per-instance import governance via instance_import_policy table
Instance import audit No Yes — Audit trail for all import events via instance_import_audit table
Artifact Promotion & Lineage
Collection artifact lineage Yes Yes — Parent-collection tracking for promoted artifacts (both editions)
Multi-target import Yes Yes — Import to multiple collection instances (local: resolves to single target)
Instance scope selector UI No Yes* — *Enterprise: multi-select component; Local: static label (local has single target)

Feature Flag Reference

All feature flags are controlled via environment variables or the configuration file. The following table documents all available flags.

Flag Default Environment Variable Description
edition local SKILLMEAT_EDITION Deployment edition: local or enterprise
auth_enabled false SKILLMEAT_AUTH_ENABLED Enforce authentication on all endpoints
auth_provider local SKILLMEAT_AUTH_PROVIDER Auth provider: local (credentials) or clerk (JWT)
enable_auto_discovery true SKILLMEAT_ENABLE_AUTO_DISCOVERY Automatically discover artifacts on startup
enable_auto_population true SKILLMEAT_ENABLE_AUTO_POPULATION Fetch GitHub metadata automatically
composite_artifacts_enabled true SKILLMEAT_COMPOSITE_ARTIFACTS_ENABLED Enable composite artifact detection
deployment_sets_enabled true SKILLMEAT_DEPLOYMENT_SETS_ENABLED Enable deployment set management
memory_context_enabled true SKILLMEAT_MEMORY_CONTEXT_ENABLED Enable memory and context system
workflow_engine_enabled true SKILLMEAT_WORKFLOW_ENGINE_ENABLED Enable workflow execution engine
workflow_artifact_sync_enabled true SKILLMEAT_WORKFLOW_ARTIFACT_SYNC_ENABLED Keep workflows in sync with artifacts
bundle_authoring_enabled true SKILLMEAT_BUNDLE_AUTHORING_ENABLED Enable bundle entity creation and editing
version_history_ui_enabled true SKILLMEAT_VERSION_HISTORY_UI_ENABLED Enable version history UI and restore operations
dvcs_branching_enabled false SKILLMEAT_DVCS_BRANCHING_ENABLED Enable artifact branching endpoints and UI (enterprise operators: see prerequisites below)
sam_telemetry_ingestion_enabled false SKILLMEAT_SAM_TELEMETRY_INGESTION_ENABLED Enable SAM telemetry data ingestion
skillbom_enabled false SKILLMEAT_SKILLBOM_ENABLED Enable SkillBOM generation (Phase 5)
modular_content_architecture false SKILLMEAT_MODULAR_CONTENT_ARCHITECTURE Enable modular content (Phase 5)
memory_auto_extract false SKILLMEAT_MEMORY_AUTO_EXTRACT Automatically extract memories from artifacts
idp_bundle_resolution_enabled false SKILLMEAT_IDP_BUNDLE_RESOLUTION_ENABLED Enable IDP bundle resolution
idp_drift_detection_enabled false SKILLMEAT_IDP_DRIFT_DETECTION_ENABLED Enable IDP drift detection
idp_content_drift_enabled false SKILLMEAT_IDP_CONTENT_DRIFT_ENABLED Enable IDP content drift tracking
rate_limit_enabled false SKILLMEAT_RATE_LIMIT_ENABLED Enable API rate limiting

Setting Feature Flags

Environment variables (recommended for deployment):

export SKILLMEAT_EDITION=enterprise
export SKILLMEAT_AUTH_ENABLED=true
export SKILLMEAT_AUTH_PROVIDER=clerk
export SKILLMEAT_SAM_TELEMETRY_INGESTION_ENABLED=true

Configuration file (~/.skillmeat/settings.toml):

[skillmeat]
edition = "enterprise"
auth_enabled = true
auth_provider = "clerk"
version_history_ui_enabled = true
sam_telemetry_ingestion_enabled = true
enable_auto_discovery = true
enable_auto_population = true

Enterprise Branching Enablement

For enterprise operators enabling dvcs_branching_enabled=true, the following prerequisites must be met. For complete implementation details, see Enterprise Parity Wave 3B: Branching.

Prerequisites: - Enterprise edition database is properly deployed and migrated (artifact_branches table includes tenant_id column) - Row-level security (RLS) policies are active on the artifact_branches table - TenantContextDep is wired in your auth middleware (tenant context set before queries execute) - The feature flag is set to true via environment variable or config file

Verification: 

# Check tenant isolation is working
psql -c "SELECT count(*) FROM artifact_branches WHERE tenant_id IS NOT NULL;"
# Should return all artifact_branches rows with non-NULL tenant_id

# Check RLS policy is active
psql -c "SELECT tablename, policyname FROM pg_policies WHERE tablename = 'artifact_branches';"
# Should show one or more active policies

Repository Implementations

The SkillMeat dependency injection system selects the appropriate repository implementation based on the configured edition. This ensures data access patterns are optimized for each backend.

Architecture Pattern

The factory functions in skillmeat/api/dependencies.py select implementations at runtime:

# Pseudo-code example
def get_artifact_repository(settings: APISettings):
    if settings.edition == "local":
        return LocalArtifactRepository()
    else:
        return EnterpriseArtifactRepository(db_session)

Repository Interface → Implementation Mapping

Interface Local Implementation Enterprise Implementation Purpose
IArtifactRepository LocalArtifactRepository EnterpriseArtifactRepository Artifact CRUD
ICollectionRepository LocalCollectionRepository EnterpriseCollectionRepository Collection management
IProjectRepository LocalProjectRepository EnterpriseProjectRepository Project scoping
IDeploymentRepository LocalDeploymentRepository EnterpriseDeploymentRepository Deployment tracking
ITagRepository LocalTagRepository EnterpriseTagRepository Tag management
ISettingsRepository LocalSettingsRepository EnterpriseSettingsRepository Settings persistence
IGroupRepository LocalGroupRepository EnterpriseGroupRepository Group organization
IContextEntityRepository LocalContextEntityRepository EnterpriseContextEntityRepository Context entity storage
IMarketplaceSourceRepository LocalMarketplaceSourceRepository EnterpriseMarketplaceSourceRepository Marketplace sources
IProjectTemplateRepository LocalProjectTemplateRepository EnterpriseProjectTemplateRepository Template management
IBundleRepository LocalBundleRepository Database-backed Bundle storage
IMembershipRepository LocalMembershipRepository Database-backed User membership
IArtifactActivityRepository LocalArtifactActivityRepository EnterpriseArtifactActivityRepository Activity logging
IDbArtifactHistoryRepository DbArtifactHistoryRepository EnterpriseArtifactHistoryStub Version history
IDbCollectionArtifactRepository DbCollectionArtifactRepository EnterpriseDbCollectionArtifactRepository Collection artifacts
IDbUserCollectionRepository DbUserCollectionRepository EnterpriseUserCollectionAdapter User collections

Key Pattern: Local implementations read/write the filesystem and SQLite; Enterprise implementations work exclusively with PostgreSQL and row-level security enforcement.

Database Schema & Migrations

Local Edition Schema

Migration file: 001_consolidated_schema.py

A single consolidated migration creates all tables for the Local edition in SQLite:

  • Collections (TOML manifest)
  • Artifacts (filesystem metadata)
  • Projects (local .claude/ directories)
  • Tags, groups, activities
  • Settings and configuration
  • Bundles, memberships, context entities
  • Deployments and project templates

Key characteristics: - Single migration for all shared functionality - Integer primary keys - SQLite-compatible types (no JSONB, UUID) - No tenant isolation columns

Enterprise Edition Schema

Migration track: Sequential ent_001 through ent_009 (PostgreSQL only)

Migration Purpose Tables Created
ent_001 Core enterprise schema Users, organizations, tenants, policies
ent_002 Tenant isolation Adds tenant_id to all resource tables, RLS policies
ent_003 Auth identity Identity providers, OIDC configuration
ent_004 Clerk integration Clerk sync tables, webhook handlers
ent_005 RBAC Roles, permissions, role assignments
ent_006 Auth audit Login history, token revocation, audit logs
ent_007 Owner polymorphism Owner-type column (user/group/service), UUID PKs
ent_008 Enterprise parity Replicates Local tables with UUID PKs and JSONB support
ent_009 Telemetry ExecutionOutcome, ProjectAgenticMetrics, rollup tables

Shared Feature Migrations

Migrations for features available in both editions are applied to both Local and Enterprise:

  • Workflows (mig_001_workflows.py): SWDL parsing, execution engine
  • Bundles (mig_002_bundles.py): Bundle entity structure (applied after edition-specific setup)
  • Attestation (mig_003_attestation.py): Code signing and verification
  • Drift detection (mig_004_drift.py): IDP drift tracking (planned)
  • Scaffolding (mig_005_scaffold.py): Project templates and bootstrap
  • Additional features as they ship

PostgreSQL-Specific Migrations

Migration file: pg_001_fulltext_search.py

Creates full-text search infrastructure (Enterprise PostgreSQL only):

  • tsvector columns on searchable tables
  • GIN indexes for fast full-text queries
  • Search rank functions and utilities
  • Not applied to Local (SQLite has limited FTS support)

Authentication Modes

SkillMeat supports three authentication approaches, with defaults and feature support varying by edition.

Mode Config Default Best For
Zero-Auth auth_enabled=false ✓ Local Personal use, development
Local Auth auth_enabled=true, auth_provider=local Enterprise (optional) Basic credential enforcement
Clerk JWT auth_enabled=true, auth_provider=clerk Enterprise option SSO, production multi-user

Zero-Auth (Default)

All API requests succeed without credentials. Every user automatically receives the local_admin identity with full system permissions.

Use when: - Building artifact collections locally - Testing features without authentication overhead - Single-developer deployments

Configuration: 

# Default behavior — no additional configuration needed
export SKILLMEAT_AUTH_ENABLED=false

Local Authentication

Basic credential-based authentication. Users provide username/password for API access.

Use when: - Need basic auth enforcement - Deploying to small teams (2-5 users) - Don't require SSO integration

Configuration: 

export SKILLMEAT_AUTH_ENABLED=true
export SKILLMEAT_AUTH_PROVIDER=local

Clerk JWT Authentication

Enterprise-grade SSO integration via Clerk. Users authenticate through your organization's identity provider.

Use when: - Deploying at organization/team scale - Requiring SAML/OIDC integration - Multi-tenant deployments (Enterprise edition)

Configuration: 

export SKILLMEAT_AUTH_ENABLED=true
export SKILLMEAT_AUTH_PROVIDER=clerk
export CLERK_API_KEY=sk_...
export CLERK_WEBHOOK_SECRET=whsec_...

Enterprise PAT (Service Clients)

Separate bootstrap authentication for non-user service clients (CI/CD, monitoring).

Use when: - Authenticating automated systems - Service-to-service communication - Machine accounts need stable credentials

Configuration: 

export SKILLMEAT_ENTERPRISE_PAT_SECRET=long-random-string

Primary Key Strategies

Local Edition: Integer PKs

All Local tables use integer auto-increment primary keys:

CREATE TABLE artifacts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  ...
);

Advantages: - Simpler to debug and reason about - Smaller index sizes - Better for SQLite performance

Limitations: - Not globally unique across multiple deployments - Can't be used for cross-deployment sync

Enterprise Edition: UUID PKs

All Enterprise tables use UUID (PostgreSQL UUID type) primary keys:

CREATE TABLE artifacts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  tenant_id UUID NOT NULL,
  ...
);

Advantages: - Globally unique across all deployments - Safe for distributed systems and replication - Better for multi-tenant isolation

Implications: - All Enterprise implementations must use UUID types - Larger index sizes (acceptable trade-off for PostgreSQL) - Compatible with replication and backup strategies

ORM Query Style

Local Edition: SQLAlchemy 1.x Query API

Local implementations use the traditional SQLAlchemy 1.x session.query() style:

# Local: SQLAlchemy 1.x query() style
artifacts = session.query(Artifact).filter(
    Artifact.project_id == project_id
).all()

Why: Simpler mental model, less verbose, well-understood patterns.

Enterprise Edition: SQLAlchemy 2.x Select API

Enterprise implementations use the modern SQLAlchemy 2.x select() style with explicit column selection:

# Enterprise: SQLAlchemy 2.x select() style
stmt = select(Artifact).where(
    Artifact.project_id == project_id,
    Artifact.tenant_id == tenant_id
)
artifacts = session.execute(stmt).scalars().all()

Why: Better support for complex queries, explicit tenant filtering, modern async support, clearer intent.

Note: This is an intentional divergence — not a technical limitation. Both styles work in both databases; the choice reflects deployment patterns and team familiarity.

Data Storage Patterns

Local Edition: Filesystem-Centric

In Local mode, the filesystem is the primary source of truth:

  • Artifacts: Stored as files/directories under ~/.skillmeat/artifacts/
  • Collections: TOML manifest at ~/.skillmeat/manifest.toml
  • Projects: Local .claude/ directories tracked by filesystem
  • SQLite cache: Derived from filesystem, refreshed on startup or via sync commands

Flow: 1. CLI/API writes to filesystem 2. Cache is refreshed synchronously 3. Web UI reads from cache

Enterprise Edition: Database-Centric

In Enterprise mode, PostgreSQL is the primary source of truth:

  • Artifacts: Stored as records in artifacts table with tenant_id isolation
  • Collections: Stored as records with full audit trails
  • Projects: Records with scope references (no local filesystem)
  • Filesystem: Optional sync point, not source of truth

Flow: 1. API writes to database 2. Web UI reads from database 3. Optional: Sync to local projects as needed

Migration & Upgrade Paths

Upgrading Local to Enterprise

SkillMeat provides migration utilities to convert from Local to Enterprise:

  1. Export artifacts and metadata from Local SQLite
  2. Transform into Enterprise PostgreSQL schema (UUID PKs, tenant_id)
  3. Import into new Enterprise PostgreSQL instance
  4. Verify data integrity and accessibility

Process is documented in: docs/user/migration/local-to-enterprise.md

Feature Flag Rollout

When enabling new features (especially experimental ones), use feature flags to control availability:

  1. Default disabled for new features
  2. Opt-in per deployment via environment variables
  3. Monitoring before broad enablement
  4. Deprecation path for old approaches

Example:

# Enable roadmap experimental features on test deployment only
export SKILLMEAT_MODULAR_CONTENT_ARCHITECTURE=true
export SKILLMEAT_SKILLBOM_ENABLED=true

API Router Support by Edition

This section documents endpoint availability and edition support across the API routers. Unless otherwise specified, endpoints in both editions work with identical semantics and return the same response formats.

Note: Enterprise edition support for most routers was significantly expanded in v2.1 (Phases 1–5). Endpoints marked with ⏳ are deferred to v2.2 pending design decisions or blocking architectural work (e.g., federation design for context sync).

Artifact Management Routers

Router/Endpoint Local Enterprise Authentication Notes
Versions & History
GET /versions Yes Yes Optional List artifact versions with pagination
POST /versions/{version_id}/restore Yes Yes Required Restore artifact to specific version
Bundles
POST /bundles Yes Yes Required Create named bundle of artifacts
PUT /bundles/{bundle_id} Yes Yes Required Update bundle metadata
DELETE /bundles/{bundle_id} Yes Yes Required Delete bundle
GET /bundles/{bundle_id}/export Yes Yes Optional Export bundle in multiple formats
POST /bundles/import Yes No Required ZIP bundle import — local only. Enterprise: use snapshot restore or artifact copy (/api/v1/enterprise-collections/{id}/restore). Returns 404 not_applicable_in_edition in enterprise.
POST /bundles/preview Yes No Optional ZIP bundle preview — local only. Enterprise: use snapshot restore. Returns 404 not_applicable_in_edition in enterprise.
POST /bundles/export Yes No Required ZIP bundle export — local only (reads local CollectionManager). Enterprise: use artifact copy endpoints. Returns 404 not_applicable_in_edition in enterprise.
Memory Items
GET /api/v1/memory-items Yes Yes Optional List memory items with pagination
GET /api/v1/memory-items/{item_id} Yes Yes Optional Get memory item details
POST /api/v1/memory-items Yes Yes Required Create memory item
PUT /api/v1/memory-items/{item_id} Yes Yes Required Update memory item
DELETE /api/v1/memory-items/{item_id} Yes Yes Required Delete memory item
GET /api/v1/memory-items/search Yes Yes Optional Search memory items
Settings
GET /api/v1/settings/github-token Yes Yes Optional Get GitHub token configuration
PUT /api/v1/settings/github-token Yes Yes Required Update GitHub token settings
GET /api/v1/settings/platform-defaults Yes Yes Optional Get platform default configuration
PUT /api/v1/settings/platform-defaults Yes Yes Required Update platform defaults
GET /api/v1/settings/entity-type-configs Yes Yes Optional List entity type configurations
GET /api/v1/settings/entity-categories Yes Yes Optional List entity categories
User Collections
POST /api/v1/user-collections Yes Yes Required Create user-scoped collection
GET /api/v1/user-collections Yes Yes Optional List user's collections
GET /api/v1/user-collections/{collection_id} Yes Yes Optional Get collection with metadata
PUT /api/v1/user-collections/{collection_id} Yes Yes Required Update collection properties
DELETE /api/v1/user-collections/{collection_id} Yes Yes Required Delete collection (soft)
GET /api/v1/user-collections/{collection_id}/artifacts Yes Yes Optional List collection members
POST /api/v1/user-collections/{collection_id}/artifacts Yes Yes Required Add artifact to collection
DELETE /api/v1/user-collections/{collection_id}/artifacts/{artifact_id} Yes Yes Required Remove artifact from collection
POST /api/v1/user-collections/{collection_id}/refresh Yes Yes Required Refresh collection metadata
Artifact Links
POST /api/v1/artifacts/{artifact_id}/linked-artifacts Yes Yes Required Create link to another artifact
GET /api/v1/artifacts/{artifact_id}/linked-artifacts Yes Yes Optional List linked artifacts
DELETE /api/v1/artifacts/{artifact_id}/linked-artifacts/{target_id} Yes Yes Required Remove artifact link
GET /api/v1/artifacts/{artifact_id}/unlinked-references Yes Yes Optional Find references without links
Artifact Legacy
GET /api/v1/artifacts Yes Yes Optional List artifacts (legacy subset)
GET /api/v1/artifacts/{artifact_id} Yes Yes Optional Get artifact details (legacy)

Project & Template Management Routers

Router/Endpoint Local Enterprise Authentication Notes
Scaffold Templates
GET /api/v1/scaffold-templates Yes Yes Optional List available project templates
GET /api/v1/scaffold-templates/{id} Yes Yes Optional Get template details
POST /api/v1/scaffold-templates Yes Yes Required Create custom template
DELETE /api/v1/scaffold-templates/{id} Yes Yes Required Delete template
Bill of Materials
GET /api/v1/bom/snapshot Yes Yes Optional Get current artifact BoM snapshot
POST /api/v1/bom/generate Yes Yes Required Generate BoM snapshot
POST /api/v1/bom/export Yes Yes Optional Export BoM in specified format
GET /api/v1/bom/verify Yes Yes Optional Verify BoM integrity and status
Cache Management
POST /api/v1/cache/refresh Yes Yes Required Refresh artifact cache (scope: all, project, artifact)
POST /api/v1/cache/invalidate Yes Yes Required Invalidate cache (scope: all, project, artifact, tier)
GET /api/v1/cache/status Yes Yes Optional Get cache status and metrics
Context Sync ⏳
GET /api/v1/context-sync/status Yes ⏳ Deferred to v2.2 Optional Get sync status and conflicts
POST /api/v1/context-sync/push Yes ⏳ Deferred to v2.2 Required Push context pack to destination
POST /api/v1/context-sync/pull Yes ⏳ Deferred to v2.2 Required Pull context pack from source

Marketplace & Source Management Routers

Router/Endpoint Local Enterprise Authentication Notes
Marketplace Sources
POST /api/v1/marketplace/sources Yes Yes Required Create GitHub repository source
GET /api/v1/marketplace/sources Yes Yes Optional List sources with pagination
GET /api/v1/marketplace/sources/{source_id} Yes Yes Optional Get source details
PATCH /api/v1/marketplace/sources/{source_id} Yes Yes Required Update source metadata
DELETE /api/v1/marketplace/sources/{source_id} Yes Yes Required Delete source
POST /api/v1/marketplace/sources/{source_id}/rescan Yes Yes Required Trigger source rescan
GET /api/v1/marketplace/sources/{source_id}/artifacts Yes Yes Optional List discovered artifacts
PATCH /api/v1/marketplace/sources/{source_id}/artifacts/{entry_id} Yes Yes Required Update artifact name
POST /api/v1/marketplace/sources/{source_id}/import Yes Yes Required Import artifacts to collection
PATCH /api/v1/marketplace/sources/{source_id}/artifacts/{entry_id}/exclude Yes Yes Required Mark artifact as excluded
DELETE /api/v1/marketplace/sources/{source_id}/artifacts/{entry_id}/exclude Yes Yes Required Restore excluded artifact
GET /api/v1/marketplace/sources/{source_id}/auto-tags Yes Yes Optional Get auto-tags from GitHub topics
PATCH /api/v1/marketplace/sources/{source_id}/auto-tags Yes Yes Required Approve/reject auto-tags
POST /api/v1/marketplace/sources/{source_id}/refresh-auto-tags Yes Yes Required Refresh auto-tags from GitHub

Enterprise-Only Routers

Enterprise edition adds specialized routers for multi-tenant and governance capabilities:

Router/Endpoint Support Authentication Notes
Enterprise Artifacts
POST /api/v1/enterprise/artifacts Enterprise Required Create tenant-scoped artifact
GET /api/v1/enterprise/artifacts Enterprise Optional List artifacts (tenant-isolated)
GET /api/v1/enterprise/artifacts/{artifact_id} Enterprise Optional Get artifact with RLS enforcement
PATCH /api/v1/enterprise/artifacts/{artifact_id} Enterprise Required Update artifact (tenant scoped); emits audit events for admin mutations
DELETE /api/v1/enterprise/artifacts/{artifact_id} Enterprise Required Delete artifact (soft, tenant scoped); emits audit events
POST /api/v1/enterprise/artifacts/{artifact_id}/deploy-global Enterprise Required Publish artifact to users
Enterprise Collections
GET /api/v1/enterprise/collections Enterprise Optional List global collections
POST /api/v1/enterprise/collections Enterprise Required Create global collection
POST /api/v1/enterprise/collections/{id}/bind Enterprise Required Bind user or team to collection
DELETE /api/v1/enterprise/collections/{id}/bindings/{binding_id} Enterprise Required Unbind user or team
DVCS Governance
POST /api/v1/governance/hard-update Both* Required Override normal update checks (requires dvcs_signature_verification=true)
GET /api/v1/governance/compliance-status Both* Optional Get compliance status (requires dvcs_signature_verification=true)
POST /api/v1/governance/sign-version Both* Required Sign specific artifact version (requires dvcs_signature_verification=true)
POST /api/v1/governance/create-gitops-pr Both* Required Create GitOps PR for hard updates (requires dvcs_signature_verification=true)
POST /api/v1/governance/trigger-cascade-update Both* Required Trigger upstream cascade with GitOps (requires dvcs_signature_verification=true)

*Enterprise-primary feature requiring system administrator role, but available in Local edition when dvcs_signature_verification=true

Enterprise mutation security boundary: All DVCS mutation operations (merge, cherry-pick, update_branch_head) route exclusively through VersionGraphService (VGS). The enterprise VGS adapter enforces _check_branch_protection as the first action in every mutation method. Callers in scaffold and ops flows bypass protection enforcement via actor.system_role allowlist ("scaffold" or "ops" values); all other callers are subject to full protection enforcement. Unauthorized mutations return HTTP 403. team_id is sourced from AuthContext (JWT claim for Clerk, None for local auth) — never hardcoded.

Authentication & Authorization

All endpoints in the routers listed above follow this pattern:

Requirement Behavior When to Use
Required Endpoint requires bearer token or API key Write operations (POST/PUT/PATCH/DELETE), sensitive reads
Optional Endpoint works with or without authentication List/get operations for public or user-owned resources
Admin-only Endpoint restricted to system administrators Enterprise-exclusive operations, governance features

For authentication configuration, see the Authentication Setup Guide.

Feature Flag Dependencies

Some routers have feature flag gates:

Router Feature Flag Default Control
Deployment Sets deployment_sets_enabled true Enable/disable deployment set endpoints
Marketplace Sources enable_auto_discovery true Auto-discovery of marketplace sources
DVCS Governance dvcs_signature_verification true Enable cryptographic governance

Section A: Per-Router API Endpoint Matrix

This section provides the definitive per-edition API endpoint support matrix. Endpoints marked not-applicable return HTTP 501 in enterprise edition with response body { "code": "enterprise_not_applicable", "detail": "..." }.

Deployment & Deployment Sets

Endpoint HTTP Method Local Enterprise Notes
POST /api/v1/deployment-sets POST Yes Yes Create deployment set
GET /api/v1/deployment-sets GET Yes Yes List deployment sets
GET /api/v1/deployment-sets/{set_id} GET Yes Yes Get deployment set details
PUT /api/v1/deployment-sets/{set_id} PUT Yes Yes Update deployment set
DELETE /api/v1/deployment-sets/{set_id} DELETE Yes Yes Delete deployment set
POST /api/v1/deployment-sets/{set_id}/deploy POST Yes not-applicable Deploy from set (local only)
POST /api/v1/deployment-sets/{set_id}/clone POST Yes Yes Clone deployment set
GET /api/v1/deployment-sets/{set_id}/resolve GET Yes Yes Resolve deployment set
POST /api/v1/deployment-sets/{set_id}/members POST Yes Yes Add member to set
GET /api/v1/deployment-sets/{set_id}/members GET Yes Yes List set members
PUT /api/v1/deployment-sets/{set_id}/members/{member_id} PUT Yes Yes Update set member
DELETE /api/v1/deployment-sets/{set_id}/members/{member_id} DELETE Yes Yes Remove set member
GET /api/v1/projects/{project_id}/pending-deployments GET — Yes List pending enterprise deployments for project
POST /api/v1/deployments/{id}/materialization POST — Yes Materialize pending deployment to local project

Selections

Endpoint HTTP Method Local Enterprise Notes
POST /api/v1/selections POST Yes Yes Create selection set
GET /api/v1/selections GET Yes Yes List selections
GET /api/v1/selections/{selection_id} GET Yes Yes Get selection details
PUT /api/v1/selections/{selection_id} PUT Yes Yes Update selection
DELETE /api/v1/selections/{selection_id} DELETE Yes Yes Delete selection
POST /api/v1/selections/{selection_id}/deploy POST Yes not-applicable Deploy selection (local only)
POST /api/v1/selections/{selection_id}/validate POST Yes Yes Validate selection

Marketplace Sources

Endpoint HTTP Method Local Enterprise Notes
POST /api/v1/marketplace/sources POST Yes Yes Create marketplace source
GET /api/v1/marketplace/sources GET Yes Yes List marketplace sources
GET /api/v1/marketplace/sources/{source_id} GET Yes Yes Get source details
PATCH /api/v1/marketplace/sources/{source_id} PATCH Yes Yes Update source
DELETE /api/v1/marketplace/sources/{source_id} DELETE Yes Yes Delete source
POST /api/v1/marketplace/sources/{source_id}/import POST Yes not-applicable Import artifacts from source (local only)
POST /api/v1/marketplace/sources/{source_id}/sync-imported POST Yes not-applicable Sync imported marketplace artifacts (local only)
POST /api/v1/marketplace/sources/{source_id}/rescan POST Yes Yes Rescan source for artifacts
POST /api/v1/marketplace/sources/{source_id}/refresh-auto-tags POST Yes Yes Refresh auto-tags from GitHub
POST /api/v1/marketplace/sources/{source_id}/entries/{entry_id}/reimport POST Yes not-applicable Reimport specific artifact (local only)
GET /api/v1/marketplace/sources/{source_id}/artifacts GET Yes Yes List discovered artifacts
PATCH /api/v1/marketplace/sources/{source_id}/artifacts/{entry_id} PATCH Yes Yes Update artifact name
POST /api/v1/marketplace/sources/{source_id}/artifacts/{entry_id}/exclude POST Yes Yes Exclude artifact
DELETE /api/v1/marketplace/sources/{source_id}/artifacts/{entry_id}/exclude DELETE Yes Yes Restore excluded artifact
GET /api/v1/marketplace/sources/{source_id}/auto-tags GET Yes Yes Get auto-tags
PATCH /api/v1/marketplace/sources/{source_id}/auto-tags PATCH Yes Yes Approve/reject auto-tags

Bundles

Endpoint HTTP Method Local Enterprise Notes
POST /api/v1/bundles POST Yes Yes Create bundle entity
GET /api/v1/bundles GET Yes Yes List bundles
GET /api/v1/bundles/{bundle_id} GET Yes Yes Get bundle details
PUT /api/v1/bundles/{bundle_id} PUT Yes Yes Update bundle
DELETE /api/v1/bundles/{bundle_id} DELETE Yes Yes Delete bundle
POST /api/v1/bundles/import POST Yes not-applicable Import ZIP bundle (local only)
POST /api/v1/bundles/preview POST Yes not-applicable Preview ZIP bundle (local only)
POST /api/v1/bundles/export POST Yes Yes Export bundle as ZIP (local uses local CollectionManager; enterprise uses artifact copy endpoints)
POST /api/v1/bundles/entities/{bundle_id}/publish POST Yes Yes Publish bundle
GET /api/v1/bundles/entities/{bundle_id}/members GET Yes Yes List bundle members
POST /api/v1/bundles/entities/{bundle_id}/members/{artifact_uuid} POST Yes Yes Add member to bundle
DELETE /api/v1/bundles/entities/{bundle_id}/members/{artifact_uuid} DELETE Yes Yes Remove bundle member

DVCS & Version History

Endpoint HTTP Method Local Enterprise Notes
GET /api/v1/versions/artifacts/{artifact_id}/history GET Yes Yes Version history timeline (Plans 1–2 compatible)
GET /api/v1/versions/artifacts/{artifact_id}/diff GET Yes Yes Version diff viewer (Plans 1–2 compatible)
POST /api/v1/versions/artifacts/{artifact_id}/restore POST Yes Yes Restore artifact to specific version (Plans 1–2 compatible)
GET /api/v1/versions/artifacts/{artifact_id}/scopes GET Yes Yes Per-user/team version scoping (enterprise-primary)
POST /api/v1/versions/artifacts/{artifact_id}/scopes/{scope_id}/promote POST Yes Yes Promotion workflow (enterprise-primary)
GET /api/v1/versions/artifacts/{artifact_id}/topology GET Yes Yes Deployment topology (enterprise-primary)
POST /api/v1/versions/artifacts/{artifact_id}/branches/{branch_name}/cherry-pick POST Yes Yes Cherry-pick between branches (Plan 1 P2 canonical endpoint)

Audit Events

Audit event tracking and querying are enterprise-only features (v0.52.0+). Available only with edition=enterprise.

Endpoint HTTP Method Local Enterprise Notes
GET /api/v1/audit-events GET No Yes List audit events with filters (tenant_id, actor_id, event_type, entity_id, trace_id, request_id, from, to, cursor, limit)
GET /api/v1/audit-events/{event_id} GET No Yes Get single audit event details
GET /api/v1/audit-events/export GET No Yes Stream audit events as NDJSON (100k event hard cap)
GET /api/v1/audit-events/event-types GET No Yes List distinct event types for filter UI population

Access control: Requires audit:read scope, granted to enterprise_admin and auditor roles. Tenant isolation enforced via RLS; queries are scoped to the authenticated user's tenant.

Correlation: All events include OpenTelemetry trace_id (W3C format) and request_id (UUID fallback) for pivoting to distributed traces in Tempo, Jaeger, Honeycomb, or Datadog. Configure deep-linking via OBSERVABILITY_TRACE_BACKEND_URL_TEMPLATE.

Pre-cutover rows: Events emitted before audit event feature shipped have trace_id: null and request_id: null.

Analytics

All 9 analytics endpoints are available in both local and enterprise editions as of enterprise-analytics-parity-v1. Enterprise edition returns tenant-scoped data (RLS enforced on artifact_metrics and artifact_version_metrics).

Endpoint HTTP Method Local Enterprise Notes
GET /api/v1/analytics/summary GET Yes Yes Usage summary; enterprise: tenant-scoped aggregate
GET /api/v1/analytics/project-summary GET Yes Yes Per-project analytics summary; enterprise: org-scoped
GET /api/v1/analytics/enterprise-summary GET Yes Yes Enterprise-wide aggregate summary (enterprise primary)
GET /api/v1/analytics/events GET Yes Yes Analytics event stream; enterprise: tenant-filtered
GET /api/v1/analytics/export GET Yes Yes Analytics data export; enterprise: tenant-scoped rows
GET /api/v1/analytics/stream GET Yes Yes Real-time analytics stream (SSE); enterprise: org-filtered
GET /api/v1/analytics/top-artifacts GET Yes Yes Top artifacts by usage; enterprise: tenant-scoped ranking
GET /api/v1/analytics/trends GET Yes Yes Usage trend aggregates; enterprise: org-scoped time series
POST /api/v1/analytics/execution-outcomes POST Yes Yes Record execution outcome; enterprise: tenant-tagged row

Note: Prior to enterprise-analytics-parity-v1, all 9 endpoints returned HTTP 501 in enterprise edition due to _require_analytics_local_edition() guard. That guard has been removed; enterprise mode now uses EnterpriseArtifactActivityRepository, EnterpriseArtifactVersionMetricsRepository, and an enterprise bundle analytics aggregator with full RLS enforcement.

Other Core Routers

Router Endpoint Prefix Local Enterprise Notes
Artifacts (CRUD) /api/v1/artifacts Yes Yes Full CRUD, metadata, links, file operations
User Collections /api/v1/user-collections Yes Yes Collection and artifact membership management
Groups /api/v1/groups Yes Yes Group organization
Tags /api/v1/tags Yes Yes Tag management
Deployments /api/v1/deployments Yes Yes Deployment CRUD and execution
Deployment Profiles /api/v1/deployment-profiles Yes Yes Profile configuration
Projects /api/v1/projects Yes Yes Project registry
Context Entities /api/v1/context-entities Yes Yes Context entity management
Memory Items /api/v1/memory-items Yes Yes Memory & Context Intelligence System
Workflows /api/v1/workflows Yes Yes Workflow CRUD and execution
Bundles (Composite) /api/v1/bundles/entities Yes Yes Named bundle entity CRUD
Marketplace Catalog /api/v1/marketplace/catalog Yes Yes Marketplace browsing and search
Settings /api/v1/settings Yes Yes Configuration and user preferences
Cache /api/v1/cache Yes Yes Cache refresh and management
Health /health/* Yes Yes Health checks and liveness/readiness probes

Section B: Per-CLI-Command Edition Support

This section documents the CLI command support matrix across local and enterprise editions.

CLI Command Local Enterprise Notes
skillmeat deploy Full Full Full support in enterprise with --profile, --all-profiles, --use-defaults flags for profile selection; DeployProfileSelector-compatible payload sent to API
skillmeat undeploy Full Full Enterprise: resolves project_path to project_id before API payload construction; scoped undeploy (not overbroad); user-facing error if path resolution fails
skillmeat history / skillmeat version list Full Full Full support in enterprise via VGS-backed history API
skillmeat branch Full Web/API-only (explicit message) Enterprise: "This command is not yet supported in enterprise edition. Use the web interface at /artifacts or the API endpoint /api/v1/artifacts/{id}/branches."
skillmeat sync-state Full Web/API-only (explicit message) Enterprise: deterministic message referencing sync endpoints
skillmeat merge Full Web/API-only (explicit message) Enterprise: deterministic message referencing web interface
skillmeat cherry-pick Full Web/API-only (explicit message) Enterprise: message references /api/v1/artifacts/{id}/branches/{branch}/cherry-pick endpoint
skillmeat add Full Full Add artifacts to collection
skillmeat sync Full Full Sync collection
skillmeat list Full Full List artifacts
skillmeat search Full Full Search artifacts
skillmeat scaffold Full Full Scaffold projects
skillmeat init Full Full Initialize collection
skillmeat config Full Full Manage configuration
skillmeat enterprise deploy pull — Full Pull pending enterprise deployments to local project
skillmeat enterprise deploy status — Full List pending vs materialized deployments
skillmeat auth login --enterprise <url> — Full Authenticate to enterprise instance
skillmeat auth status — Full Show current enterprise auth status
skillmeat auth logout — Full Clear enterprise auth config
skillmeat init --pull-pending — Full Initialize project and pull pending enterprise deployments

Error Message Template (Stub Commands)

For commands not yet supported in enterprise edition (branch, sync-state, merge, cherry-pick), the CLI emits:

Error: This command is not yet supported in enterprise edition.
Use the web interface at /artifacts or the API endpoint {specific_endpoint}.
Documentation: https://docs.skillmeat.dev/user/guides/cli-reference.html#enterprise-limitations

Section C: Per-Web-Surface Edition Support

This section documents edition support for web UI surfaces and their deploy/management flows.

Web Surface Component Path Local Enterprise Edition-Specific Behavior Wave
Context Deploy Dialog skillmeat/web/components/context/deploy-to-project-dialog.tsx Full Full Enterprise: DeployProfileSelector wired (three modes: deployment_profile_ids[], use_project_defaults, all_profiles); legacy selector removed (P5)
Version Deploy Action skillmeat/web/components/version/version-deploy-action.tsx Full Full Compact confirm-dialog; passes version_id only (no profile selection UI). Profile targeting is the caller's responsibility via the calling context's deploy dialog.
Version Deploy Hook skillmeat/web/hooks/use-version-deploy.ts Full Full Enterprise: passes deployment_profile_ids and use_project_defaults alongside version_id in POST /api/v1/deploy request
Cherry-Pick UI Cherry-pick button/modal in artifact detail view Full Full Enterprise: uses canonical endpoint /api/v1/artifacts/{id}/branches/{branch_name}/cherry-pick
Collection Deploy Dialog skillmeat/web/components/deploy/collection-deploy-dialog.tsx Full Best-aligned Enterprise: deploy collection; no profile selector needed (collection-level operation)
Deployment Set Deploy Deploy button in deployment set card/modal Full not-applicable (501) Enterprise: 501 Not Implemented; UI displays "Not available in enterprise edition" message instead of generic error Current
Artifact Filters & Lists Main artifact browser, saved filters, grouping views Full Full Enterprise: all collection/grouping features supported with tenant isolation
Settings & Preferences User settings, notification preferences, configuration panels Full Full Enterprise: team-scoped and org-level configuration options
Marketplace Browse Marketplace listings, source management UI Full Full Enterprise: all discovery features work; import operations return 501 Current

Deploy Profile Selector Component

The DeployProfileSelector component is the canonical deployment profile selection surface for enterprise edition. It renders three distinct modes:

  1. Profile List (checkbox array)
  2. Displays available deployment profiles
  3. User can select multiple profiles

  4. Maps to deployment_profile_ids: string[]

  5. Use Project Defaults (boolean toggle)

  6. When enabled, deploy uses project's default profiles

  7. Maps to use_project_defaults: boolean

  8. All Profiles (boolean toggle)

  9. When enabled, deploy applies to all available profiles
  10. Maps to all_profiles: boolean

The context deploy dialog (deploy-to-project-dialog.tsx) and version deploy action (version-deploy-action.tsx) both wire this component and pass all three fields to the API request. Legacy selectors have been removed from both surfaces.

501 Handling in Web UI and CLI

Surfaces that call local-only endpoints (deployment set deploy, selection deploy, marketplace import/sync/reimport, bundle import) detect HTTP 501 responses and display:

"Not available in enterprise edition.
For team deployments, use the web interface or contact your administrator."

Instead of showing a generic "Internal Server Error" message.

FastAPI 501 error nesting: FastAPI wraps error details under body.detail.code (not body.code). All web API error-handling paths (web/lib/api.ts, web/lib/api/deployment-sets.ts) and the CLI parse body.detail.code for enterprise 501 responses.

Summary: Edition Decision Matrix

Use this matrix to quickly determine which edition and configuration is right for your deployment:

Requirement Local Enterprise
Personal/single-user ✓ —
Local development ✓ —
Multiple users/teams — ✓
Organizational RBAC — ✓
Multi-tenant SaaS — ✓
Zero-config setup ✓ —
External database required — ✓
High availability/replication — ✓
Full-text search — ✓
Filesystem-native workflow ✓ —

Enterprise Version Features Implementation Status

The following version history capabilities were fully implemented in Phase 9 (Enterprise Backend Parity) and are now production-ready in enterprise edition:

Feature Implementation Status Endpoint API Reference
Version history timeline ✅ Phase 9 Complete GET /api/v1/versions/artifacts/{id}/history Cursor-based pagination, max 100 items
Version diff viewer ✅ Phase 9 Complete GET /api/v1/versions/artifacts/{id}/diff Unified diff format between any two versions
Restore by hash ✅ Phase 9 Complete POST /api/v1/versions/artifacts/{id}/restore Non-destructive restore with new version entry
Per-user scoping ✅ Phase 9 Complete GET /api/v1/versions/artifacts/{id}/scopes Filter by user/team/enterprise hierarchy
Per-team scoping ✅ Phase 9 Complete GET /api/v1/versions/artifacts/{id}/scopes Owner-hierarchy filtering
Promotion workflow ✅ Phase 9 Complete POST /api/v1/versions/artifacts/{id}/scopes/{scope_id}/promote State machine: none → pending → approved → rejected
Divergence monitoring ✅ Phase 9 Complete GET /api/v1/versions/scopes/{scope_id}/review Detect source conflicts and divergence
Admin force-sync ✅ Phase 9 Complete POST /api/v1/versions/scopes/{scope_id}/force-sync Override conflicts, admin-only
Bulk admin actions ✅ Phase 9 Complete POST /api/v1/versions/admin/bulk-action Batch restore/purge operations
Deployment topology ✅ Phase 9 Complete GET /api/v1/versions/artifacts/{id}/topology Which projects have artifact deployed
Composite atomic restore ✅ Phase 9 Complete POST /api/v1/versions/artifacts/{id}/restore All members restore together or not at all
Version backfill ✅ Phase 9 Complete POST /api/v1/versions/backfill/trigger Seed initial versions for pre-VCS artifacts
Version backfill status ✅ Phase 9 Complete GET /api/v1/versions/backfill/status Monitor backfill progress

Related documentation: See .claude/context/key-context/version-history-patterns.md for complete API patterns and .claude/findings/version-history-patterns-audit-2026-04-12.md for audit verification.

Next Steps