Project Overlays¶

Personal project overlays let you customize how a project materializes without affecting the shared canonical state your team sees. Think of an overlay as a personal layer of configuration applied only to your local deployments.

What Are Overlays?¶

An overlay captures three types of customizations for a project:

Environment variable overrides — Set or override MY_VAR=value pairs for your local deployments
Artifact version pins — Pin a specific skill, command, or agent to a particular version on your workstation, even if the team uses a different version
Draft-state marker — Mark a project as "draft" locally to prevent accidental deployments while you're experimenting

Key principle: Overlays are always private to you. Other team members see the canonical project state unchanged. When you run skillmeat enterprise deploy pull, the overlay is automatically merged with the canonical configuration before materialization.

Use Cases¶

Environment variables: You're testing with a staging API endpoint while the team uses production.

skillmeat project override set API_ENDPOINT https://api-staging.example.com

Version pins: You want to test a pre-release skill version before the team approves it for deployment.

skillmeat project override set artifact:my-skill v2.0.0-beta.1

Draft state: You're iterating on project configuration and don't want to accidentally deploy incomplete changes.

# UI: Toggle the "Draft" switch on the project detail page
# OR CLI: (draft state managed via UI in current version)

Local Edition (File-Based Overlays)¶

In the local edition, overlays are stored in a TOML file at:

~/.skillmeat/overlays/{project_id}.toml

Example Local Overlay File¶

# Environment variable overrides
[env_vars]
API_ENDPOINT = "https://api-staging.example.com"
DEBUG_LEVEL = "trace"

# Artifact version pins (format: artifact:<name> = "version")
[version_pins]
"artifact:my-skill" = "v2.0.0-beta.1"
"artifact:utils" = "v1.5.0"

# Draft state flag
draft = false

Changes to this file are immediately reflected in the next CLI operation — no server sync needed.

Enterprise Edition (Database-Backed Overlays)¶

In the enterprise edition, overlays are stored securely in the enterprise_project_user_overlays database table, with Row-Level Security (RLS) enforcing that you can only see and modify your own overlays.

Setting Overrides via CLI¶

# List all current overrides for a project
skillmeat project override list --project my-project

# Set an environment variable
skillmeat project override set API_ENDPOINT https://api-staging.example.com

# Set an artifact version pin
skillmeat project override set artifact:my-skill v2.0.0-beta.1

# View a specific override
skillmeat project override get API_ENDPOINT

# Remove an override
skillmeat project override unset API_ENDPOINT

Managing Overlays via UI¶

On the project detail page (enterprise edition only):

Environment Variables section — Click "Edit" to open the overlay editor
Add new variables with "Add Variable"
Click on values to edit inline
Click the "X" to remove a variable
Click "Save" to persist your overlay
Artifact Versions section — Click on any artifact version chip to pin to a specific version
Select a version from the version history
The chip changes color to indicate it's pinned (distinct from canonical)
Click the pin icon again to remove the pin
Draft State indicator — Toggle the "Draft" switch at the top right
Draft projects display a warning before deployment
Teammates always see the canonical (non-draft) state

How Overlays Merge with Canonical State¶

When you run skillmeat enterprise deploy pull (or equivalent CLI operation), the merge happens in this order:

Start with canonical state — The team-approved project configuration from the server
Apply environment variable overrides — Your env vars are appended/replaced (not replaced wholesale)
Apply artifact version pins — Pinned versions override the canonical versions; unpinned artifacts use canonical versions
Apply draft-state marker — If you marked the project as draft, the materialized project refuses deployment until you unmark it

Example Merge Behavior¶

Canonical project:

[env]
API_ENDPOINT = "https://api.example.com"
LOG_LEVEL = "info"

[artifacts]
my-skill = "v1.0.0"
utils = "v1.2.0"

Your overlay:

[env_vars]
API_ENDPOINT = "https://api-staging.example.com"  # Override

[version_pins]
"artifact:my-skill" = "v2.0.0-beta.1"  # Pin specific version
# utils is NOT pinned, so canonical v1.2.0 will be used

Materialized result:

[env]
API_ENDPOINT = "https://api-staging.example.com"  # Your override
LOG_LEVEL = "info"                                # Canonical

[artifacts]
my-skill = "v2.0.0-beta.1"   # Your pin
utils = "v1.2.0"             # Canonical (not pinned)

Important: Overlays Cannot Grant Access¶

Overlays are not an ACL escape hatch. Even if you override an artifact version or environment variable, you still cannot:

Access artifacts you don't have permission to deploy
Override role-based access control (RBAC) restrictions
Bypass team-level approval workflows

If a team member hasn't granted you permission to an artifact, pinning a version of it locally will fail during materialization with a permission error.

Clearing Overlays¶

Remove a Single Override¶

skillmeat project override unset API_ENDPOINT

Clear Your Entire Overlay¶

Delete the overlay file (local edition):

rm ~/.skillmeat/overlays/{project_id}.toml

Or via UI (enterprise edition): Click "Clear All Overrides" on the project detail page.

Using `--no-overlay` to Force Canonical State¶

If you want to force deployment with the canonical (team-approved) state and ignore your overlays:

skillmeat enterprise deploy pull --no-overlay

This is useful for: - Validating that the canonical configuration works on your workstation - Deploying a teammate's project without applying your personal customizations - Troubleshooting configuration conflicts

Deferred: Cross-Workstation Overlay Sync¶

Current limitation (v1): Overlays are tied to a single workstation. If you set an overlay on Workstation A, you'll need to re-set it manually on Workstation B.

Planned for v1.1: - Export/import overlay configurations between workstations - Server-side overlay sync for enterprise deployments across multiple machines - Conflict resolution strategies when overlays diverge between workstations

If cross-workstation sync is critical for your workflow, reach out to support to prioritize this feature.

Troubleshooting¶

Q: Why doesn't my environment variable override show up in the materialized project?

A: Check that the env var name matches exactly (case-sensitive). Also verify you've run skillmeat enterprise deploy pull after setting the override — local changes don't apply automatically.

Q: Can I export my overlays as a backup?

A: Yes. For local edition, the TOML file is your backup — version control it or copy it to a USB drive. For enterprise edition, overlays are stored in the database and automatically backed up with your enterprise instance. Contact your admin for export procedures.

Q: I pinned a version but it's still deploying the old version. What happened?

A: Version pins are only applied during skillmeat enterprise deploy pull. If you're using the web UI to deploy directly, overlay version pins are not applied (this is intentional to prevent divergence between CLI and web deployments). Always use the CLI for overlay-aware deployments.

Q: Can teammates see my overlays?

A: No. Overlays are completely private via Row-Level Security (enterprise) or local-only TOML files (local edition). Teammates always see the canonical state.