commands

Overview ¶

provision_credentials.go — provision support for OrgCredential resources.

Mirrors playbook.go shape: list, match by name, upsert. Idempotent: re-running with the same YAML produces NOOPs after the first apply.

Schema (studio/credentials/<name>.yaml):

name: slack-webhook-milestones
credential_type: webhook
description: Slack incoming webhook for #milestones channel
values:
  default_url:
    secret_env: SLACK_WEBHOOK_MILESTONES   # CI-friendly
  # OR
  default_url:
    secret_vault: taufinity/slack-webhook-milestones   # local: shells out to token-vault
  # Plain (non-secret) values:
  auth_header:
    value: Authorization

Resolution order per field: value → secret_env → secret_vault. Exactly one must be set per field; provision fails loud if zero or multiple are set.

Secrets never touch disk. They're read at apply time, marshalled into a JSON blob, and posted to the credentials API which encrypts at rest.

provision_image_taxonomy.go — provision support for the per-org image classification taxonomy.

PHASE-A STUB. The image_tags lookup table and its accompanying taxonomy storage land in Phase B4 of the image-asset POC. The taxonomy is referenced by the classify_image playbook step (added in Phase B3); the step validates produced tags against the vocabulary server-side. Until B4 lands, this handler validates the YAML schema and prints the intended action.

Plan reference: cto-as-a-service/docs/plans/2026-05-13-efteling-image-asset-poc.md

provision_images.go — provision support for seeding image knowledge files from a manifest of source URLs.

Flow per entry:

1. download bytes from source_url
2. name-based dedupe BEFORE upload (no classify cost on re-runs): if an image KnowledgeFile with the same derived name already exists in the org, skip
3. resize down to download_max_dim longest edge if larger (cheap storage + keeps payload under the 25 MB upload cap)
4. POST multipart to /api/knowledge-files (the real upload endpoint; never a direct DB write)
5. the org's router rule (source=knowledge_file, mime~image/*) then auto-triggers the classify_image playbook asynchronously

Idempotent: re-running on an already-seeded org is a NOOP (step 2).

ground_truth_tags in the manifest are for offline eval only — they are NOT sent to the classify step (that's the model's job).

Plan reference: cto-as-a-service/docs/plans/2026-05-13-efteling-image-asset-poc.md

provision_knowledge.go — provision support for knowledge files (price lists, templates, golden records).

Calls POST /api/admin/knowledge-files/upsert (admin endpoint) which:

• matches existing rows by (org_id, name [, file_type]),
• short-circuits to NOOP if SHA256(content) == existing.Checksum,
• writes a v1 version snapshot on initial CREATE,
• tags the version row with X-Change-Source: provision (set by provision_client.go).

Each YAML file under studio/knowledge-base/ becomes one knowledge file. `content_path` (preferred) loads from a sibling file on disk so big price lists don't bloat the YAML; `content` (inline) is supported for small payloads.

provision_playbooks.go — provision support for playbook resources.

Mirrors the dashboards.go pattern: list, match by name, upsert, then reconcile child rows (steps). Idempotent: re-running with the same YAML produces NOOPs after the first apply.

Versioning: every PUT/POST hits the standard /api/playbooks endpoints, which call SaveVersionWithSummary internally. The X-Change-Source: provision header is set automatically by the client (see provision_client.go), which the handlers honour via middleware.ResolveChangedByType — version rows are tagged "provision" instead of "user"/"system".

provision_prompts.go — provision support for org-scoped customer-tunable prompt templates.

Backs the no-deploy prompt-edit path: editing

<customer>/studio/prompts/<name>.txt

and running `taufinity provision apply` pushes the new body to the Studio prompt_templates row for that org. The change takes effect on next generation (within the loader's 60s cache TTL — see services.PromptLoader in ai-site-gen).

Each .txt file becomes one row. Name = filename minus .txt — matches the convention used by site config's content_guidelines_path and by the existing templates/prompts/ directory on the server.

Idempotent: the server-side handler uses ON CONFLICT (organization_id, name) DO UPDATE, so re-running with no content change is a no-op write (same body), and a body change is an in-place update.

provision_router_rules.go — provision support for router rules.

Phase B2 activates this handler. It now:

1. Auto-creates a knowledge_file source-type router for the org if one doesn't exist (one router per org per source_type is enough — each carries N rules).
2. Resolves the dispatch playbook by name → ID.
3. Translates YAML conditions to the JSON config blob expected by the internal/router knowledge_file_match evaluator.
4. Match-by-Name on rules within the router; PUT existing or POST new. Uniqueness is enforced server-side by migration 184's partial unique index on (router_id, name).

provision_site_settings.go — provision support for three per-site settings sections that steer content generation:

• general-settings.yaml → PUT /api/sites/{id}/settings/general description, enabled, show_excerpt — the description feeds {{.Description}} in topic_generation.txt.
• content-settings.yaml → PUT /api/sites/{id}/settings/content category, format, tone, length, keywords, languages — feed {{.Category}}, {{.Format}}, {{.Tone}} in the prompts.
• metadata-settings.yaml → PUT /api/sites/{id}/settings/metadata free-form keys; conventionally target_audience lives here and feeds {{.TargetAudience}}. The metadata handler accepts any keys, so this struct is intentionally a map.

Same shape as provisionAISettings (provision_sites.go): read YAML → marshal JSON → PUT → log. Missing file is a clean no-op, matching ai-settings.yaml. Idempotent — re-running with no content change is a no-op write; a field change is an in-place update.

Versioning: each PUT is recorded as one entity_versions row on site_config via the X-Change-Source: provision header (see provision_client.go writeWithHeaders).

provision_test_suites.go — provision support for test suite resources.

Pattern mirrors provision_playbooks.go: list → name-match → upsert → reconcile cases. The suite's target playbook is resolved from a name to a numeric ID at apply time, so the YAML never carries environment-specific IDs.

provision_widgets.go — provision support for chat widget resources.

Pattern mirrors provision_playbooks.go: list, match by name, upsert. Widgets do not have child rows in our model, so reconciliation is single-call.