Organization Sync (SaaS IDE)

Organization management for the CFactory SaaS IDE lives in a hosted control plane (or the cfactory-admin React + shadcn UI in this monorepo). The CLI runtime (packages/cfactory-cli) is the only sync consumer. Editors inherit via cfactory serve.

Hard invariants

1. Organization artifacts never enter a git worktree (no writes to .cfactory/, AGENTS.md, or marketplace-style project installs).
2. Org and user content coexist (source: "organization" vs user). Same basename does not clobber.
3. Free-form mergeDeep of /api/config is rejected. Only allowlisted keys apply.

Allowlisted /api/config

Accepted:

• skills.urls (HTTPS indexes pulled into ~/.cache/cfactory/org/<orgId>/skills/)
• commands.urls / hooks.urls (+ hooks.enforce) — pulled into org cache; never into the worktree
• instructions (HTTPS URLs only)
• cfactory.org (models, providers, mcp, hooks, extra skill/command/instruction/hook URLs)

cfactory.org.models fields:

• allow / deny / defaultModel
• agentModels — map of mode name → provider/model (e.g. plan → cfactory/opus)
• routingPreference — cost | balance | quality (Bifrost Auto routing bias; default balance)
• requireAutoModel — when true, members may only use cfactory-auto/* (gateway 403 + client catalog filter); concrete allow/deny still applies to Auto routing targets
• allowLocalModelOverrideByProject — map of projectId → boolean (resolved against org-bindings.json)
• allowLocalModelOverride — optional global fallback

When allowLocalModelOverride is false for the bound project:

• CLI applies defaultModel and agentModels (falling back to defaultModel for modes without an entry) and clears sticky model.json per-mode picks.
• IDE disables model changes in Settings → Models, Mode Edit, and the chat model picker.

Auto virtual models (cfactory-auto/* and gateway-owned cfactory/smart) resolve as follows: cfactory/smart is orchestrated in the gateway (cheap classifier → concrete model). Other Auto tiers still resolve in Bifrost; the gateway injects org routingPreference and allowed concrete model ids on those requests.

cfactory.org.providers fields (structured; never free-form provider merge):

• enabled — CFly staff master switch for the org
• allowCustom — org admin: members may add local custom providers
• catalog — org-published provider entries (id, name, npm, baseURL, models) with no secrets

Ignored (examples): permission, mcp, agent, formatter, tui, provider, skills.paths.

CLI entrypoints

Sync runs on Config load for TUI, cfactory run, and cfactory serve. Acceptance: org skills/rules appear without the VS Code extension installed.

Org model/provider policy is applied at runtime:

• When allowLocalModelOverride is false for the bound project, local model / small_model / subagent_model / agent.*.model overrides are ignored and org defaultModel / agentModels are applied.
• When unlocked, org agentModels fill missing local agent.*.model entries only (user overrides win).
• Provider catalog entries are additive; local OpenAI-compatible custom providers are stripped when staff has not enabled the feature or the admin has disabled custom adds.
• consoleManagedProviders is populated from the org catalog.
• The model catalog is pre-filtered with modelAllowed().

Project bind

~/.config/cfactory/org-bindings.json maps directory or git remote → organizationId + projectId. The CLI sets CFACTORY_PROJECT_ID for gateway usage headers.

Model policy

Gateway returns 403 for disallowed models. Catalog endpoints filter the list. Client UI filter alone is insufficient.

Provider policy

Admin UI: Governance → Providers. Staff toggle lives on the Organization page when profile.user.staff is true.

Admin UI kit

packages/cfactory-admin uses React + shadcn + Tailwind, dark-first, primary #d2006f (CFly brand pink). It does not use Solid cfactory-ui.