Enterprise Governance Guide

This guide covers enterprise artifact governance in SkillMeat, including how system administrators create and manage enterprise-owned artifacts, how enforcement works, and what permissions different user roles have.

Table of Contents

• Overview
• What Are Enterprise-Managed Artifacts?
• Understanding the Enterprise Badge
• Creating Enterprise Artifacts
• Global Deployment
• Artifact Enforcement
• User Permissions by Role
• Enterprise Dashboard
• Importing Local Collections
• Best Practices
• Troubleshooting

Overview

Enterprise governance in SkillMeat allows organizations to:

• Create centrally-managed artifacts owned at the enterprise level (not by individual users or teams)
• Enforce consistent versions across the organization with the enforce_override setting
• Deploy globally to all team and user collections simultaneously
• Control permissions based on user roles (system admin, team admin, team member, viewer)
• Audit changes with detailed logs of who created/modified enterprise artifacts
• Prevent local modifications when enforcement is enabled, ensuring organizational consistency

Key Concepts

Owner Types: SkillMeat recognizes three owner types: - User: Owned by an individual user (personal artifacts) - Team: Owned by a team (collaborative, team-member artifacts) - Enterprise: Owned at the organization level (managed by system admins)

User Roles: Four role levels control what users can do: 1. System Admin — Full administrative access across the entire organization 2. Team Admin — Administrative access within a specific team 3. Team Member — Standard member access within a team 4. Viewer — Read-only access (default for new users)

What Are Enterprise-Managed Artifacts?

Enterprise-managed artifacts are skills, commands, agents, and other artifact types that are:

• Owned by the enterprise (not by an individual or team)
• Created and updated by system administrators only
• Read-only for regular users (viewing permitted, editing/deleting blocked)
• Deployable globally to all downstream collections in a single operation
• Subject to enforcement — when enabled, local copies cannot be modified

Real-World Examples

Common use cases for enterprise artifacts:

• Organization-wide skills — A shared "company-standard-sdk" skill that all teams depend on
• Compliance templates — Standardized security audit agents that meet regulatory requirements
• Best-practice commands — Organization-wide CLI commands for common workflows
• Brand assets — Standardized context modules with brand guidelines and design systems
• Critical workflows — Multi-step workflow definitions that coordinate across teams

Understanding the Enterprise Badge

The Badge and Lock Icon

When browsing artifacts in the web UI, enterprise-managed artifacts display:

• "Enterprise Managed" badge (purple badge with organization icon) — Indicates the artifact is owned and managed at the enterprise level
• Lock icon — When enforce_override is enabled, a padlock icon shows the artifact cannot be locally modified

What the Badge Means for You

What You See	Your Role	What You Can Do
"Enterprise Managed" badge, no lock	Regular user	View the artifact, read its content, use it in workflows
"Enterprise Managed" badge + lock	Regular user	View only (no local modifications allowed)
"Enterprise Managed" badge	System admin	Full control: create, update, delete, deploy globally

Creating Enterprise Artifacts

Only system administrators can create enterprise-owned artifacts.

Via Web Dashboard

1. Navigate to the Enterprise Dashboard (Admin menu → Enterprise)
2. Click Create Enterprise Artifact
3. Fill in the artifact details:
4. Name: Human-readable identifier (e.g., company-sdk)
5. Type: Artifact type (skill, command, agent, composite, etc.)
6. Source (optional): Upstream GitHub URL for tracking
7. Initial Content (optional): Markdown content; creates an initial version
8. Metadata (optional): Custom key-value fields
9. Tags: For organization and discoverability
10. Click Create

The artifact is now enterprise-owned and ready for deployment.

Via API (System Admins)

Create an enterprise artifact using the enterprise artifacts API:

curl -X POST http://localhost:8080/api/v1/enterprise/artifacts \
  -H "Authorization: Bearer $ENTERPRISE_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "company-sdk",
    "artifact_type": "skill",
    "source": "myorg/company-sdk",
    "content": "# Company SDK Skill\n\nShared SDK for all teams.",
    "tags": ["sdk", "enterprise"],
    "metadata": {
      "version": "1.0.0",
      "owner": "platform-team"
    }
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "company-sdk",
  "artifact_type": "skill",
  "source_url": "myorg/company-sdk",
  "tags": ["sdk", "enterprise"],
  "metadata": {"version": "1.0.0", "owner": "platform-team"},
  "owner_type": "enterprise",
  "is_active": true,
  "created_at": "2026-03-27T10:00:00Z",
  "updated_at": "2026-03-27T10:00:00Z"
}

Global Deployment

Global deployment pushes an enterprise artifact to all downstream team and user collections in your organization.

Via Web Dashboard

1. Open an enterprise artifact
2. Click the Deploy Globally button
3. Choose enforcement mode:
4. Enforce Override (default) — Silently overwrite local copies with no confirmation
5. Notify Only — Send notifications to downstream owners instead of auto-overwriting
6. Click Deploy

A deployment task is enqueued and you'll see a status indicator showing progress.

Via API

curl -X POST http://localhost:8080/api/v1/enterprise/artifacts/{artifact_id}/deploy-global \
  -H "Authorization: Bearer $ENTERPRISE_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "enforce_override": true
  }'

Response:

{
  "task_id": "task-550e8400-e29b-41d4-a716",
  "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "enforce_override": true,
  "message": "Global deployment accepted. Task enqueued for processing."
}

Deployment Modes

Enforce Override (enforce_override=true): - Enterprise artifact replaces local copy immediately - No merge prompts or notifications - Ensures organizational consistency - Use for critical, frequently-updated artifacts

Notify Only (enforce_override=false): - Notifications sent to downstream owners - Owners can decide whether to pull the update - Gentler approach, preserves local customizations - Good for suggestions, optional updates

Artifact Enforcement

When enforce_override is enabled on an artifact, the lock icon appears and:

• Local modifications are blocked — Users cannot edit or delete the artifact from their personal/team collections
• Updates are forced — New versions deployed from the enterprise automatically overwrite local copies
• Read access remains — Users can still view and use the artifact
• Sync is automatic — The sync engine applies updates automatically without user intervention

How Enforcement Works

1. System admin creates and publishes an enterprise artifact
2. During global deployment, enforce_override: true is set
3. The sync engine forces the artifact to all downstream collections
4. Users see the artifact with a lock icon and "read-only" indication
5. When the enterprise version updates, changes push automatically
6. Local attempts to modify throw a permission error

Disabling Enforcement

System admins can change enforcement post-deployment:

# Update artifact to disable enforcement
curl -X PATCH http://localhost:8080/api/v1/enterprise/artifacts/{artifact_id} \
  -H "Authorization: Bearer $ENTERPRISE_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "enforce_override": false
  }'

Once disabled, lock icons disappear and users can modify their local copies.

User Permissions by Role

System Admin

Full enterprise artifact control: - Create, read, update, delete enterprise artifacts - Deploy globally (with or without enforcement) - Update enforcement settings - Access the Enterprise Dashboard - View all artifacts across the organization - Manage users and team memberships

Team Admin

Team-scoped control: - Read enterprise artifacts (view only) - Create/manage artifacts in their team scope - Manage team membership and team-member roles - Cannot create enterprise artifacts - Cannot modify enforcement settings

Team Member

Limited collaborative access: - Read team and personal artifacts - Cannot modify enterprise artifacts - Cannot create enterprise scope - Standard user permissions

Viewer

Read-only access: - View artifacts shared with them - Cannot create or modify artifacts - Cannot perform any write operations - Useful for stakeholders, auditors, observers

Enterprise Dashboard

The Enterprise Dashboard (available to system admins) provides a central hub for enterprise governance:

Dashboard Features

1. Artifact Management
2. List all enterprise artifacts
3. Quick-create new artifacts

4. View enforcement status and deployment history

5. Global Operations

6. Deploy artifacts to all collections
7. Monitor deployment progress

8. View rollout status and error logs

9. Sync Status

10. Monitor sync health across the organization
11. View last-sync timestamps for all collections

12. Identify sync failures or stale collections

13. User & Team Management

14. List all users and their roles
15. Manage team memberships
16. Promote/demote team admins

17. Audit role assignments

18. Audit Trail

19. View history of artifact creates/updates/deletes
20. See who deployed what and when
21. Track enforcement changes
22. Review sync operations

Accessing the Dashboard

1. Log in as a system admin
2. Click the Admin menu (gear icon)
3. Select Enterprise Dashboard
4. Navigate between tabs for artifacts, users, sync status, and audit logs

Importing Local Collections

When migrating from local SkillMeat to an enterprise deployment, you can import your personal collection into the enterprise database using the skillmeat enterprise import CLI command.

Why Import?

Importing your local collection to enterprise allows you to: - Centralize artifact management with your team - Share personal skills and commands with colleagues - Eliminate duplicate storage (CAS dedup prevents redundant copies) - Maintain artifact history and metadata - Prepare artifacts for enterprise governance and promotion

Import Command Reference

skillmeat enterprise import [OPTIONS]

Options:

Option	Type	Default	Description
--from-collection	PATH	~/.skillmeat/collection/	Path to local collection directory to import from
--filter-type	TEXT	None	Only import artifacts of this type (e.g., skill, command, agent)
--filter-tag	TEXT	None	Only import artifacts with this tag
--dry-run	FLAG	False	Preview what would be imported without writing to the database
--tier	INT (1-3)	3	Tier assignment for imported artifacts (1=Shared, 2=Team, 3=Personal/Dev)
--conflict	STRING	skip	How to handle duplicate artifacts: skip (ignore), overwrite (replace), create_version (create new version)

Import Workflow

The import process follows these steps:

1. Read your local collection from the specified directory
2. Analyze artifacts and compute SHA-256 hashes for deduplication
3. Check the enterprise database for existing matches
4. Apply your conflict strategy:
5. skip — Ignore artifacts that already exist (default, safest)
6. overwrite — Replace existing artifacts with your versions
7. create_version — Create new versions for conflicting artifacts
8. Upload content to CAS storage (Artifact Blob Store) with automatic deduplication
9. Preserve metadata: tags, source links, deployment history, and custom fields
10. Report summary: N created, M skipped, K conflicted

Tier Assignment

Imported artifacts are assigned to the tier you specify (default: Tier 3 — personal/dev scope):

• Tier 1 (Shared/Enterprise) — Organization-wide artifacts (requires admin promotion)
• Tier 2 (Team) — Team-scoped artifacts (visible to team only)
• Tier 3 (Personal/Dev) — Personal/draft artifacts (visible only to you)

Important: Imported artifacts default to draft status. A system administrator must explicitly promote them to production status via the Enterprise Dashboard or API before they are deployable organization-wide.

Example Invocations

Preview import without writing:

# See what would be imported from your local collection
skillmeat enterprise import --dry-run

# Output:
# [INFO] Preview mode — no changes will be written
# [INFO] Artifacts to import: 12
# [INFO] Artifacts to skip (existing): 3
# [INFO] Total space to use: 4.2 MB (CAS dedup: 1.8 MB)

Import only skills, skip duplicates:

skillmeat enterprise import --filter-type skill --conflict skip

Import from custom location, overwrite conflicts:

skillmeat enterprise import \
  --from-collection /path/to/custom/collection \
  --conflict overwrite

Import as Tier 1 (shared organization) artifacts:

skillmeat enterprise import --tier 1

Import everything with all options:

skillmeat enterprise import \
  --from-collection /Users/jane/skillmeat/collection/ \
  --filter-tag "internal-only" \
  --tier 2 \
  --conflict create_version

Import vs Upload

Operation	Use When	Access Level
Import	Migrating from local SkillMeat to enterprise	Requires CLI access to enterprise API
Create (via dashboard)	Uploading from the web UI	Available to all users in enterprise
Upload (individual files)	Adding file content after artifact creation	Requires artifact write permissions

Deduplication (CAS)

The import process uses Content-Addressable Storage (CAS) to store file content efficiently:

• Identical artifacts are stored only once (SHA-256 hash-based dedup)
• Storage cost is proportional to unique content, not duplicate count
• If 5 developers import the same skill, only one copy is stored
• Metadata (tags, descriptions) is preserved per artifact even for deduplicated content

Example:

Local Collections Import:
  - user-a: my-skill (v1.0, 50 KB)
  - user-b: my-skill (v1.0, 50 KB)  ← Identical content
  - user-c: my-skill (v1.0, 50 KB)  ← Identical content

Enterprise Storage:
  - 1 blob (50 KB, SHA-256: abc123...)
  - 3 artifact records (one per user) pointing to same blob
  - Effective storage: 50 KB + metadata (not 150 KB)

Handling Conflicts

When the import encounters an artifact with the same name in the enterprise database, your chosen conflict strategy determines what happens:

Skip (default):

skillmeat enterprise import --conflict skip

- Existing enterprise artifacts are left untouched - Your import is recorded as skipped - Safest option for first-time imports

Overwrite:

skillmeat enterprise import --conflict overwrite

- Existing artifact content is replaced with your version - Version history is preserved (old versions remain readable) - Use when you want to push your latest updates

Create Version:

skillmeat enterprise import --conflict create_version

- Your artifact becomes a new version of the existing artifact - Both old and new versions coexist - Allows side-by-side comparison and rollback - Useful when merging contributions from multiple developers

Troubleshooting Import

"Insufficient permissions" error:

Error: You do not have permission to import artifacts

Solution: Only users with appropriate enterprise roles can import. Ask your system administrator to grant you import permissions.

"Collection directory not found":

Error: Collection not found: /path/to/collection/

Solution: Check that the path exists and that you have read access:

ls -la ~/.skillmeat/collection/

Import appears slow: - Large collections (100+ artifacts) may take several minutes - Check your network connection - Verify the enterprise server is responsive: skillmeat status - For very large imports, use --filter-type to import in batches

Dry-run counts don't match actual import: - This indicates the enterprise database changed between dry-run and import - Re-run --dry-run to get updated counts - Use --conflict skip to safely import again

Best Practices

Creating Enterprise Artifacts

1. Use clear, descriptive names — company-sdk, security-audit-agent, not artifact-v2
2. Add metadata and tags — Help team members discover and understand the artifact's purpose
3. Document with content — Provide comprehensive Markdown content explaining usage, examples, and requirements
4. Track the source — Link to the upstream GitHub repository when applicable
5. Get stakeholder input — Review with affected teams before publishing

Deployment Strategy

1. Start with notify-only — Test new artifacts with enforce_override: false to gather feedback
2. Graduate to enforcement — Once stable, enable enforcement to ensure consistency
3. Schedule deployments — Deploy during low-activity periods if possible
4. Monitor sync health — Check the Enterprise Dashboard after deployment
5. Communicate changes — Notify users about new deployments via email or Slack

Enforcement Decisions

Use enforcement (lock) for: - Critical compliance artifacts - Frequently-updated SDKs - Security-sensitive workflows - Standardized processes that must not deviate

Use notify-only for: - Optional enhancements - Best-practice suggestions - Non-critical updates - Artifacts teams customize locally

Access Control

1. Assign system admins carefully — Limited to platform/infrastructure teams
2. Use team admins for delegation — Distribute governance to team leads
3. Default to viewer — New users start with read-only access
4. Audit role changes — Review promotion requests and team membership changes
5. Document ownership — Track which team manages which artifact via metadata

Troubleshooting

"Insufficient permissions" when creating artifacts

Cause: Only system admins can create enterprise artifacts.

Solution: Ask your system administrator to grant you the system_admin role.

Deployment appears stuck

Cause: Large deployments or network issues can take time.

Solution: 1. Check the Enterprise Dashboard for status 2. Use the task ID to poll deployment progress 3. If truly stuck, contact your system administrator to investigate logs

Local copy won't sync with enterprise version

Cause: Sync engine may be delayed or experiencing errors.

Solution: 1. Refresh your browser (F5) 2. Manually trigger a sync via the UI (if available) 3. Wait for automatic sync (typically <5 minutes) 4. Check with system admin if issues persist

Enforce override blocking needed local changes

Cause: The artifact is locked with enforcement enabled.

Solution: 1. Work with your system administrator to disable enforcement (if appropriate) 2. Or request the enterprise team update the artifact instead 3. Or branch to a separate user-owned artifact for local customization

Missing Enterprise Dashboard

Cause: You don't have system admin role.

Solution: Ask your system administrator to grant you the system admin role, or contact your team admin for assistance.

See Also

• Server Setup Guide — Configure enterprise edition and authentication
• Team Sharing Guide — Share artifacts with teammates
• Authentication Setup — Set up user authentication