Skip to main content

CaSc And Config Cascade

Most users can configure Synth in the web UI. Teams and Kubernetes operators should also understand CaSc, the Configuration-as-Code document that makes installs repeatable.

CaSc is pronounced cask.

Mental Model​

built-in defaults
  -> global settings
  -> project settings
  -> explicit agent settings

Project settings win over global settings. Global locks can prevent projects from overriding sensitive fields.

CaSc can encode both global settings and project overrides:

global_settings:
  default_provider: opencode
  default_model: gpt-5.4-mini
  agents:
    extract:
      provider: opencode
      model: gpt-5.4-mini
      batch_size: 2
  providers:
    opencode:
      enabled: true
      credential_id: helm-opencode
      base_url: https://opencode.ai/zen/v1

locks:
  agents.extract.model: true
  providers.opencode.credential_id: true

projects:
  docs:
    default_provider: opencode
    default_model: gpt-5.4-mini
    backend:
      type: git
      config:
        remote_url: https://github.com/your-org/synth-knowledge.git
        branch: main
        auto_push: true
        auto_pull: true
        sync_on_create: true
        project_subdir: projects/docs
        credential_id: github-read-token
    schema:
      categories:
        - name: Guides
          directory: guides
          description: How-to guides and setup workflows.
        - name: Reference
          directory: reference
          description: API, CLI, and configuration reference.
        - name: Tutorials
          directory: tutorials
          description: Step-by-step learning material.
        - name: Troubleshooting
          directory: troubleshooting
          description: Known issues and remediation steps.
    agents:
      extract:
        prompt: Project-specific extraction instructions.
        batch_size: 3
    watchers:
      docs-main:
        type: git
        repo: https://github.com/example/docs
        branch: main
        interval: 3600
        files:
          rules:
            - name: Public docs
              include:
                - "docs/**/*.{md,mdx,markdown}"
        auto_start: false
      roadmap:
        type: jira
        repo: https://example.atlassian.net
        credential: jira-prod
        interval: 300
        auto_start: false
        config:
          jql: 'project = ABC AND updated >= -30d ORDER BY updated DESC'
          comments:
            mode: latest
            limit: 10
          privacy:
            user_display: display_name
            include_emails: false

Use Cases​

  • set one default provider for all projects
  • let a project choose a different extraction model
  • lock production provider credentials
  • customize prompts and selected agent runtime knobs
  • preconfigure project providers
  • export/import config for repeatable deployments
  • define watchers before a project is first opened

Secrets​

CaSc should not contain real API keys, Git tokens, or Jira API tokens. Exports mask provider keys as ***, keep watcher credentials as credential IDs, and the importer ignores masked values.

Use schema for project categories in new CaSc. The importer also accepts scheme as a compatibility alias for older configuration files.

Use:

  • web credentials for normal installs
  • environment variables for local development
  • Kubernetes Secrets for Helm installs

Practical Advice​

Start with the web UI. Use CaSc after you have more than one project or environment, or whenever you want a new install to come up with projects, agents, and watchers already defined.

For Kubernetes, use Helm + CaSc.