Explain Wizard

The explain wizard helps you understand SCC configuration behavior, why plugins are blocked or denied, and how inheritance works.

Quick Start

/scc-wizard:explain

Then ask questions like:

“Why is plugin X blocked for team Y?”
“What’s the effective config for team backend?”
“Why didn’t my team config changes take effect?”

Response Format

The wizard gives short answers first with copy/paste fixes:

Short answer: Plugin X is denied because team 'backend' is not in
delegation.teams.allow_additional_plugins.

To fix: Add "backend" to delegation.teams.allow_additional_plugins

Want full reasoning? [y/N]

What Can I Ask?

”Why is plugin X blocked?”

The wizard checks in order:

Does it match security.blocked_plugins? → Blocked (immutable)
Does it match defaults.disabled_plugins? → Disabled (can re-enable)
Is team not in delegation.teams.allow_additional_plugins? → Denied
Does it not match defaults.allowed_plugins? → Denied

”Why is MCP server X blocked?”

Checks in order:

Does it match security.blocked_mcp_servers? → Blocked
Is it stdio type and allow_stdio_mcp = false? → Blocked
Is stdio command not absolute path? → Blocked
Is stdio command outside allowed_stdio_prefixes? → Blocked
Is team not in delegation.teams.allow_additional_mcp_servers? → Denied
Does URL not match defaults.allowed_mcp_servers? → Denied

”What’s the effective config for team X?”

Shows the final computed configuration after all merges:

Org defaults applied
Team profile additions
Security boundaries enforced
What actually runs

”Explain delegation for team X”

Shows:

Team’s position in delegation allowlists
Whether project overrides are enabled
What the team can and cannot add

Blocked vs Denied vs Disabled

Term	Meaning	Can Fix?	Source
Blocked	Security boundary	No	`security.blocked_*`
Denied	Governance decision	Yes	Delegation or allowlist
Disabled	Removed from defaults	Yes	`defaults.disabled_plugins`

Copy/Paste Fixes

The wizard provides ready-to-use JSON snippets:

Allow a Plugin Pattern

{
  "defaults": {
    "allowed_plugins": ["*@sandboxed-code-official", "core-*"]
  }
}

Delegate Plugin Additions to a Team

{
  "delegation": {
    "teams": {
      "allow_additional_plugins": ["*"]
    }
  }
}

Enable Project Overrides

{
  "delegation": {
    "projects": { "inherit_team_delegation": true }
  }
}

Then for the specific team:

{
  "profiles": {
    "backend": {
      "delegation": { "allow_project_overrides": true }
    }
  }
}

Grant Team Marketplace Trust

{
  "profiles": {
    "ai-team": {
      "trust": {
        "allow_additional_marketplaces": true,
        "marketplace_source_patterns": ["https://github.com/myorg/*"]
      }
    }
  }
}

Inheritance Model

SCC merges configs in layers:

Layer 1: Org config (org-v1)
   ↓ (apply defaults)
Layer 2: Team profile OR team-managed team-config
   ↓ (if delegation allows)
Layer 3: Project .scc.yaml additions
   ↓
Effective config (what actually runs)

Merge Rules by Field

Field	Rule
`enabled_plugins`	Accumulate (union)
`disabled_plugins`	Remove from enabled
`additional_mcp_servers`	Accumulate
`security.blocked_*`	Immutable, all layers
`session.timeout_hours`	Last-wins
`network_policy`	Org defaults with stricter-only team overrides
`cache_ttl_hours`	Org defaults only

Common Questions

”Why didn’t my team config changes take effect?”

Check:

Is your team team-managed? (config_source must exist)
Is config_source URL correct and accessible?
Has the cache expired?
Are plugins formatted as plugin@marketplace?
Does the marketplace exist?

Quick fix if config seems stale:

rm ~/.cache/scc/org_config.json ~/.cache/scc/cache_meta.json

Then rerun your command.

”Why is blocked_mcp_servers not blocking a plugin’s MCP?”

security.blocked_mcp_servers only checks explicitly-declared MCP servers in org/team/project configs. It does not inspect MCP servers bundled inside marketplace plugins.