@knowzai/cli 0.1.0

package/assets/portable/docker-compose.yml

@@ -0,0 +1,444 @@
+# Knowz Portable — customer-runnable PULL kit (spec OPS_PortableImageRelease N2 / R6).
+# Requires Docker Compose v2.20+ (`depends_on.required` and external deactivation overlays).
+#
+# ZERO-SOURCE: every app service pulls a PREBUILT private GHCR image (no build context, no repo checkout).
+# Derived from the in-repo docker-compose.portable.yml, with every `build:` block replaced by an `image:`
+# ref. Seven services, ZERO Azure resources: Postgres+pgvector, MinIO, Redis, the platform API, the
+# Knowz.Worker enrichment host, the SPA, and the MCP server.
+#
+# QUICKSTART (see docs/CUSTOMER_PORTABLE_QUICKSTART.md):
+#   docker login ghcr.io                 # with your GHCR_PULL_TOKEN (read:packages)
+#   cp .env.example .env                 # then edit .env: KNOWZ_VERSION + REAL secrets
+#   docker compose -f docker-compose.yml up -d
+#
+# IMAGE SELECTION:
+#   KNOWZ_VERSION  — the platform release, e.g. 0.2.0 (REQUIRED; fail-closed).
+#   KNOWZ_FLAVOR   — "" (empty, default) pulls the Azure/stub/BYO-OpenAI-compat portable build;
+#                    "-gcp" pulls the Vertex-flavored portable build. api/worker => :X.Y.Z-portable[-gcp];
+#                    web/mcp are cloud-neutral => plain :X.Y.Z.
+#
+# FAIL-CLOSED CREDS: every secret uses ${VAR:?message} — `up` aborts with a clear message if any is unset.
+# There are NO committed prod-shaped defaults.
+#
+# Access: web http://localhost:3000 | API http://localhost:5000/swagger | MCP http://localhost:3001.
+# Postgres, Redis, and MinIO are intentionally available only on the internal Compose network.
+
+services:
+  # ── Postgres + pgvector: KnowzMaster + KnowzKnowledge, `vector` + `pg_trgm` extensions ─────────────
+  postgres:
+    image: pgvector/pgvector:pg16
+    # Register enlists MasterDb + KnowledgeDb in one TransactionScope, which Npgsql
+    # escalates to a 2PC PREPARE TRANSACTION across the two databases. The pgvector
+    # image defaults max_prepared_transactions=0 (→ 55000 "prepared transactions are
+    # disabled"); enable it (sized to match the default max_connections).
+    command: ["postgres", "-c", "max_prepared_transactions=100"]
+    environment:
+      POSTGRES_USER: "${PG_USER:-knowz}"
+      POSTGRES_PASSWORD: "${PG_PASSWORD:?PG_PASSWORD must be set in .env}"
+      POSTGRES_DB: postgres
+    volumes:
+      - knowz-portable-pgdata:/var/lib/postgresql/data
+      # Kit-local init (shipped in this directory) — creates the DBs + extensions on first cluster init.
+      - ./postgres-initdb:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      # Succeeds only once the init script has created KnowzKnowledge — gates API/worker start on a ready DB.
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d KnowzKnowledge"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 20s
+
+  # ── MinIO: S3-compatible object store ──────────────────────────────────────────────────────────────
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: "${MINIO_ROOT_USER:-knowzminio}"
+      MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set in .env (>=8 chars)}"
+    volumes:
+      - knowz-portable-miniodata:/data
+    healthcheck:
+      test: ["CMD-SHELL", "mc ready local || curl -f http://localhost:9000/minio/health/ready || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+  # ── One-shot: wait for MinIO, create the portable bucket, then exit (gates API/worker on bucket-ready) ─
+  minio-createbucket:
+    image: minio/mc:latest
+    depends_on:
+      minio:
+        condition: service_started
+    environment:
+      MINIO_ROOT_USER: "${MINIO_ROOT_USER:-knowzminio}"
+      MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set in .env}"
+      MINIO_BUCKET: "${MINIO_BUCKET:-knowz-portable}"
+      MINIO_APP_ACCESS_KEY: "${MINIO_APP_ACCESS_KEY:-knowzapp}"
+      MINIO_APP_SECRET_KEY: "${MINIO_APP_SECRET_KEY:?MINIO_APP_SECRET_KEY must be set in .env}"
+    entrypoint: >
+      /bin/sh -c "
+      until mc alias set local http://minio:9000 \"$${MINIO_ROOT_USER}\" \"$${MINIO_ROOT_PASSWORD}\"; do
+        echo 'waiting for minio...'; sleep 2;
+      done;
+      mc mb --ignore-existing local/$${MINIO_BUCKET};
+      mc anonymous set none local/$${MINIO_BUCKET} || true;
+      printf '{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:GetBucketLocation\",\"s3:ListBucket\",\"s3:ListBucketMultipartUploads\"],\"Resource\":[\"arn:aws:s3:::%s\"]},{\"Effect\":\"Allow\",\"Action\":[\"s3:GetObject\",\"s3:PutObject\",\"s3:DeleteObject\",\"s3:AbortMultipartUpload\",\"s3:ListMultipartUploadParts\"],\"Resource\":[\"arn:aws:s3:::%s/*\"]}]}\n' "$${MINIO_BUCKET}" "$${MINIO_BUCKET}" > /tmp/knowz-portable-app-policy.json;
+      mc admin policy create local knowz-portable-app /tmp/knowz-portable-app-policy.json;
+      mc admin user add local "$${MINIO_APP_ACCESS_KEY}" "$${MINIO_APP_SECRET_KEY}";
+      mc admin policy attach local knowz-portable-app --user "$${MINIO_APP_ACCESS_KEY}";
+      echo 'private bucket and scoped application identity ready';
+      "
+
+  # ── Redis: cache / model-selector cache ────────────────────────────────────────────────────────────
+  redis:
+    image: redis:7
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 10
+      start_period: 5s
+
+  # ── API: platform API. Auto-creates the Postgres schema on first boot; publishes jobs to PortableQueueJobs ─
+  api:
+    # Prebuilt portable image. ""=azure/stub/BYO-OpenAI-compat build; KNOWZ_FLAVOR=-gcp => Vertex build.
+    image: "${KNOWZ_REGISTRY:-ghcr.io/knowz-io}/knowz-api:${KNOWZ_VERSION:?KNOWZ_VERSION must be set in .env (the platform release, e.g. 0.2.0)}-portable${KNOWZ_FLAVOR:-}"
+    ports:
+      - "${BIND_ADDRESS:-127.0.0.1}:${API_PORT:-5000}:8080"
+    depends_on:
+      postgres:
+        condition: service_healthy
+        required: false
+      redis:
+        condition: service_healthy
+        required: false
+      minio-createbucket:
+        condition: service_completed_successfully
+        required: false
+    # Reach a host-local OpenAI-compatible endpoint (e.g. Ollama on the host) at host.docker.internal.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      ASPNETCORE_ENVIRONMENT: Staging
+      ASPNETCORE_URLS: http://+:8080
+
+      # ── Portable substrate provider switches (the three subsystem axes) ──────────────────────────
+      Knowz__Database__Provider: Postgres
+      Knowz__Queue__Provider: Postgres
+      Knowz__Storage__Provider: "${STORAGE_PROVIDER:-MinioS3}"
+      Knowz__Storage__FileSystem__RootPath: "/data/objects"
+      Knowz__Search__Provider: Postgres
+
+      # ── Postgres connection strings (Npgsql format) + first-boot schema bring-up ─────────────────
+      ConnectionStrings__KnowledgeDb: "Host=${PG_HOST:-postgres};Port=${PG_PORT:-5432};Database=KnowzKnowledge;Username=${PG_USER:-knowz};Password=${PG_PASSWORD:?PG_PASSWORD must be set};Ssl Mode=${PG_SSL_MODE:-Prefer}${PG_EXTRA_OPTIONS:-}"
+      ConnectionStrings__MasterDb: "Host=${PG_HOST:-postgres};Port=${PG_PORT:-5432};Database=KnowzMaster;Username=${PG_USER:-knowz};Password=${PG_PASSWORD:?PG_PASSWORD must be set};Ssl Mode=${PG_SSL_MODE:-Prefer}${PG_EXTRA_OPTIONS:-}"
+      Database__AutoMigrate: "true"
+
+      # ── Embedding (offline deterministic stub by default; MUST match the pgvector column dim) ──────
+      Embedding__Provider: "${EMBEDDING_PROVIDER:-Stub}"
+      Embedding__ModelName: "${EMBEDDING_MODEL_NAME:-text-embedding-3-small}"
+      Embedding__Dimensions: "${EMBEDDING_DIMENSIONS:-1536}"
+      Embedding__Endpoint: "${EMBEDDING_ENDPOINT:-}"
+      Embedding__ApiKey: "${EMBEDDING_API_KEY:-}"
+      # OpenAI direct is configured through the OpenAiCompat provider (Option A), not Embedding__Provider.
+      OpenAI__ApiKey: "${OPENAI_API_KEY:-}"
+
+      # ── MinIO object storage + its credential (via the portable config-backed ISecretStore) ──────
+      Knowz__Storage__Minio__Endpoint: "${S3_ENDPOINT:-http://minio:9000}"
+      Knowz__Storage__Minio__Bucket: "${MINIO_BUCKET:-knowz-portable}"
+      Knowz__Storage__Minio__ForcePathStyle: "${S3_FORCE_PATH_STYLE:-true}"
+      Knowz__Storage__Minio__Region: "${S3_REGION:-us-east-1}"
+      PortableSecrets__MinioAccessKeyId: "${MINIO_APP_ACCESS_KEY:-knowzapp}"
+      PortableSecrets__MinioSecretAccessKey: "${MINIO_APP_SECRET_KEY:?MINIO_APP_SECRET_KEY must be set}"
+
+      # ── Redis ─────────────────────────────────────────────────────────────────────────────────────
+      Redis__ConnectionString: "${REDIS_CONNECTION_STRING:-redis:6379}"
+      ConnectionStrings__Redis: "${REDIS_CONNECTION_STRING:-redis:6379}"
+      DataProtection__KeyRingPath: "/var/lib/knowz/data-protection-keys"
+
+      # ── Licensing: empty defaults preserve the unlinked portable behavior ──────────────────────
+      Knowz__Licensing__MothershipUrl: "${KNOWZ_LICENSING_MOTHERSHIP_URL:-}"
+      Knowz__Licensing__InstallCredential: "${KNOWZ_LICENSING_INSTALL_CREDENTIAL:-}"
+      Knowz__Licensing__InstallationId: "${KNOWZ_LICENSING_INSTALLATION_ID:-}"
+
+      # ── Auth — fail-closed (omit any of these and `up` aborts) ────────────────────────────────────
+      Jwt__Secret: "${JWT_SECRET:?JWT_SECRET must be set in .env (>=32 random chars)}"
+      Jwt__Key: "${JWT_SECRET}"
+      JwtSettings__Secret: "${JWT_SECRET}"
+      Authentication__Jwt__Secret: "${JWT_SECRET}"
+      SuperAdmin__Passphrase: "${SUPERADMIN_PASSPHRASE:?SUPERADMIN_PASSPHRASE must be set in .env}"
+
+      # ── MCP service-to-service key (must match the mcp container) ────────────────────────────────
+      MCP__ServiceKey: "${MCP_SERVICE_KEY:?MCP_SERVICE_KEY must be set in .env}"
+
+      InternalApi__Key: "${INTERNAL_API_KEY:?INTERNAL_API_KEY must be set in .env (must match worker)}"
+
+      PlatformOrganization__Slug: "${PLATFORM_ORG_SLUG:-knowz}"
+      PlatformOrganization__Name: "${PLATFORM_ORG_NAME:-Knowz}"
+
+      AzureOpenAI__Endpoint: "${AZURE_OPENAI_ENDPOINT:-}"
+      AzureOpenAI__ApiKey: "${AZURE_OPENAI_API_KEY:-}"
+      PortableSecrets__openai--primary--key: "${AZURE_OPENAI_API_KEY:-}"
+
+      # ── BYOK cloud perception (optional; each cloud axis is opt-in and customer-billed) ──────────
+      AzureAIVision__Endpoint: "${AZUREAIVISION__ENDPOINT:-}"
+      AzureAIVision__ApiKey: "${AZUREAIVISION__APIKEY:-}"
+      AzureAIVision__Features: "${AZUREAIVISION__FEATURES:-}"
+      DocumentIntelligence__Endpoint: "${DOCUMENTINTELLIGENCE__ENDPOINT:-}"
+      DocumentIntelligence__ApiKey: "${DOCUMENTINTELLIGENCE__APIKEY:-}"
+      DocumentIntelligence__UseManagedIdentity: "${DOCUMENTINTELLIGENCE__USEMANAGEDIDENTITY:-false}"
+      AzureOpenAI__WhisperDeploymentName: "${AZUREOPENAI__WHISPERDEPLOYMENTNAME:-}"
+      AzureOpenAI__TranscriptionDeploymentName: "${AZUREOPENAI__TRANSCRIPTIONDEPLOYMENTNAME:-}"
+      AzureOpenAI__Transcription__Endpoint: "${AZUREOPENAI__TRANSCRIPTION__ENDPOINT:-}"
+      AzureOpenAI__Transcription__ApiKey: "${AZUREOPENAI__TRANSCRIPTION__APIKEY:-}"
+      AssemblyAi__ApiKey: "${ASSEMBLYAI__APIKEY:-}"
+      AssemblyAi__EnableBatchPremiumTier: "${ASSEMBLYAI__ENABLEBATCHPREMIUMTIER:-false}"
+      Knowz__CloudProvider__RealtimeTranscription: "${KNOWZ__CLOUDPROVIDER__REALTIMETRANSCRIPTION:-}"
+      Enrichment__FaceRecognition__Enabled: "${ENRICHMENT__FACERECOGNITION__ENABLED:-false}"
+      FaceRecognition__MatchThreshold: "${FACERECOGNITION__MATCHTHRESHOLD:-}"
+
+      # ── CORS: allow the SPA origin ──────────────────────────────────────────────────────────────
+      KNOWZ_EXTRA_CORS_ORIGINS: "${PUBLIC_WEB_ORIGIN:-http://localhost:${WEB_PORT:-3000}}"
+
+      # ── Outbound link origin ────────────────────────────────────────────────────────────────────
+      # Every mailed link (invites, verification, share CTAs, /m/{shortCode}) and the device-code
+      # approval URL resolve through WebAppUrl. Left unset, the image's baked appsettings.json wins
+      # and a customer's portable install mails links to https://dev.knowz.io — Knowz's own dev
+      # environment. Confirmed live on a 0.34.4 portable install, 2026-07-28.
+      WebAppUrl: "${PUBLIC_WEB_ORIGIN:-http://localhost:${WEB_PORT:-3000}}"
+      PUBLIC_WEB_ORIGIN: "${PUBLIC_WEB_ORIGIN:-http://localhost:${WEB_PORT:-3000}}"
+
+      # ── AI provider selection (all optional; empty => offline stub, so the default `up` is unchanged) ─
+      #    * Google Vertex (Gemini): KNOWZ_FLAVOR=-gcp image + KNOWZ__CLOUDPROVIDER__AI=Gcp + VERTEX__PROJECT,
+      #      ADC mounted read-only below. * BYO OpenAI-compatible (OpenAI/Together/Ollama/vLLM/LM Studio):
+      #      KNOWZ__CLOUDPROVIDER__AI=OpenAiCompat + OPENAICOMPAT__ENDPOINT/CHATMODEL/EMBEDDINGMODEL
+      #      (works on the default "" flavor — vendor-neutral, no -gcp image needed). See the quickstart. ──
+      Knowz__CloudProvider: "${KNOWZ__CLOUDPROVIDER:-}"
+      Knowz__CloudProvider__Ai: "${KNOWZ__CLOUDPROVIDER__AI:-}"
+      Knowz__CloudProvider__DocIntelligence: "${KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE:-}"
+      Knowz__CloudProvider__Vision: "${KNOWZ__CLOUDPROVIDER__VISION:-}"
+      Knowz__CloudProvider__Transcription: "${KNOWZ__CLOUDPROVIDER__TRANSCRIPTION:-}"
+      Vertex__Project: "${VERTEX__PROJECT:-}"
+      Vertex__Region: "${VERTEX__REGION:-}"
+      Vertex__ChatModel: "${VERTEX__CHATMODEL:-}"
+      Vertex__EmbeddingModel: "${VERTEX__EMBEDDINGMODEL:-}"
+      Vertex__EmbeddingDimensions: "${VERTEX__EMBEDDINGDIMENSIONS:-1536}"
+      # BYO OpenAI-compatible endpoint (N3). ChatModel + EmbeddingModel are REQUIRED when selected (no
+      # universal default — boot fails loud naming the key). ApiKey optional (Ollama/vLLM run keyless).
+      # EmbeddingDimensions MUST match Embedding__Dimensions / the pgvector column (local models often 384/768).
+      OpenAiCompat__Endpoint: "${OPENAICOMPAT__ENDPOINT:-}"
+      OpenAiCompat__ApiKey: "${OPENAICOMPAT__APIKEY:-}"
+      OpenAiCompat__ChatModel: "${OPENAICOMPAT__CHATMODEL:-}"
+      OpenAiCompat__EmbeddingModel: "${OPENAICOMPAT__EMBEDDINGMODEL:-}"
+      OpenAiCompat__EmbeddingDimensions: "${OPENAICOMPAT__EMBEDDINGDIMENSIONS:-}"
+      # Points at the neutral read-only ADC mount below only when host ADC is configured. Keeping the
+      # well-known gcloud path vacant lets Google's credential chain reach GCE metadata ADC when unset.
+      GOOGLE_APPLICATION_CREDENTIALS: "${GCLOUD_ADC_PATH:+/gcloud/adc.json}"
+    volumes:
+      # Host Application Default Credentials, READ-ONLY (:ro) — NO service-account key files. Defaults to
+      # /dev/null (always present, inert) so the stub/offline/OpenAI-compat default `up` still works; for the
+      # Google AI flavor run `gcloud auth application-default login` once on the host, then set
+      # GCLOUD_ADC_PATH to the ABSOLUTE path of ~/.config/gcloud/application_default_credentials.json in .env.
+      - "${GCLOUD_ADC_PATH:-/dev/null}:/gcloud/adc.json:ro"
+      - knowz-portable-objectsdata:/data/objects
+      - knowz-portable-identity:/var/lib/knowz/identity
+      - knowz-portable-dpkeys:/var/lib/knowz/data-protection-keys
+    # The aspnet:10.0 runtime image ships no curl/wget — run an HTTP readiness probe
+    # over bash /dev/tcp and assert a 200 status line (/health/ready, /healthz fallback).
+    # Migrations complete before Kestrel binds 8080, so a 200 means the API is ready.
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >-
+          timeout 5 bash -c '{ exec 3<>/dev/tcp/127.0.0.1/8080 && printf "GET /health/ready HTTP/1.0\r\n\r\n" >&3 && head -1 <&3 | grep -q 200; } || { exec 3<>/dev/tcp/127.0.0.1/8080 && printf "GET /healthz HTTP/1.0\r\n\r\n" >&3 && head -1 <&3 | grep -q 200; }'
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 90s
+
+  # ── Worker: Knowz.Worker BackgroundService — drains PortableQueueJobs + enrichment auto-driver ─────
+  worker:
+    image: "${KNOWZ_REGISTRY:-ghcr.io/knowz-io}/knowz-worker:${KNOWZ_VERSION:?KNOWZ_VERSION must be set in .env (the platform release, e.g. 0.2.0)}-portable${KNOWZ_FLAVOR:-}"
+    depends_on:
+      postgres:
+        condition: service_healthy
+        required: false
+      redis:
+        condition: service_healthy
+        required: false
+      minio-createbucket:
+        condition: service_completed_successfully
+        required: false
+      api:
+        condition: service_healthy
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      DOTNET_ENVIRONMENT: Staging
+      ASPNETCORE_ENVIRONMENT: Staging
+
+      Knowz__Database__Provider: Postgres
+      Knowz__Queue__Provider: Postgres
+      Knowz__Storage__Provider: "${STORAGE_PROVIDER:-MinioS3}"
+      Knowz__Storage__FileSystem__RootPath: "/data/objects"
+      Knowz__Search__Provider: Postgres
+
+      # Same reason as on the api service: the Worker mails links too (summaries, engagement
+      # invites), and without this it inherits the image's baked https://dev.knowz.io.
+      WebAppUrl: "${PUBLIC_WEB_ORIGIN:-http://localhost:${WEB_PORT:-3000}}"
+
+      ConnectionStrings__KnowledgeDb: "Host=${PG_HOST:-postgres};Port=${PG_PORT:-5432};Database=KnowzKnowledge;Username=${PG_USER:-knowz};Password=${PG_PASSWORD:?PG_PASSWORD must be set};Ssl Mode=${PG_SSL_MODE:-Prefer}${PG_EXTRA_OPTIONS:-}"
+      ConnectionStrings__MasterDb: "Host=${PG_HOST:-postgres};Port=${PG_PORT:-5432};Database=KnowzMaster;Username=${PG_USER:-knowz};Password=${PG_PASSWORD:?PG_PASSWORD must be set};Ssl Mode=${PG_SSL_MODE:-Prefer}${PG_EXTRA_OPTIONS:-}"
+      Database__AutoMigrate: "false"
+
+      Embedding__Provider: "${EMBEDDING_PROVIDER:-Stub}"
+      Embedding__ModelName: "${EMBEDDING_MODEL_NAME:-text-embedding-3-small}"
+      Embedding__Dimensions: "${EMBEDDING_DIMENSIONS:-1536}"
+      Embedding__Endpoint: "${EMBEDDING_ENDPOINT:-}"
+      Embedding__ApiKey: "${EMBEDDING_API_KEY:-}"
+      OpenAI__ApiKey: "${OPENAI_API_KEY:-}"
+
+      Knowz__Storage__Minio__Endpoint: "${S3_ENDPOINT:-http://minio:9000}"
+      Knowz__Storage__Minio__Bucket: "${MINIO_BUCKET:-knowz-portable}"
+      Knowz__Storage__Minio__ForcePathStyle: "${S3_FORCE_PATH_STYLE:-true}"
+      Knowz__Storage__Minio__Region: "${S3_REGION:-us-east-1}"
+      PortableSecrets__MinioAccessKeyId: "${MINIO_APP_ACCESS_KEY:-knowzapp}"
+      PortableSecrets__MinioSecretAccessKey: "${MINIO_APP_SECRET_KEY:?MINIO_APP_SECRET_KEY must be set}"
+
+      Redis__ConnectionString: "${REDIS_CONNECTION_STRING:-redis:6379}"
+      ConnectionStrings__Redis: "${REDIS_CONNECTION_STRING:-redis:6379}"
+      DataProtection__KeyRingPath: "/var/lib/knowz/data-protection-keys"
+
+      # ── Licensing: empty defaults preserve the unlinked portable behavior ──────────────────────
+      Knowz__Licensing__MothershipUrl: "${KNOWZ_LICENSING_MOTHERSHIP_URL:-}"
+      Knowz__Licensing__InstallCredential: "${KNOWZ_LICENSING_INSTALL_CREDENTIAL:-}"
+      Knowz__Licensing__InstallationId: "${KNOWZ_LICENSING_INSTALLATION_ID:-}"
+
+      ApiBaseUrl: "http://api:8080"
+      InternalApi__Key: "${INTERNAL_API_KEY:?INTERNAL_API_KEY must be set in .env (must match api)}"
+
+      PlatformOrganization__Slug: "${PLATFORM_ORG_SLUG:-knowz}"
+      PlatformOrganization__Name: "${PLATFORM_ORG_NAME:-Knowz}"
+
+      AzureOpenAI__Endpoint: "${AZURE_OPENAI_ENDPOINT:-}"
+      AzureOpenAI__ApiKey: "${AZURE_OPENAI_API_KEY:-}"
+      PortableSecrets__openai--primary--key: "${AZURE_OPENAI_API_KEY:-}"
+
+      # ── BYOK cloud perception (optional; each cloud axis is opt-in and customer-billed) ──────────
+      AzureAIVision__Endpoint: "${AZUREAIVISION__ENDPOINT:-}"
+      AzureAIVision__ApiKey: "${AZUREAIVISION__APIKEY:-}"
+      AzureAIVision__Features: "${AZUREAIVISION__FEATURES:-}"
+      DocumentIntelligence__Endpoint: "${DOCUMENTINTELLIGENCE__ENDPOINT:-}"
+      DocumentIntelligence__ApiKey: "${DOCUMENTINTELLIGENCE__APIKEY:-}"
+      DocumentIntelligence__UseManagedIdentity: "${DOCUMENTINTELLIGENCE__USEMANAGEDIDENTITY:-false}"
+      AzureOpenAI__WhisperDeploymentName: "${AZUREOPENAI__WHISPERDEPLOYMENTNAME:-}"
+      AzureOpenAI__TranscriptionDeploymentName: "${AZUREOPENAI__TRANSCRIPTIONDEPLOYMENTNAME:-}"
+      AzureOpenAI__Transcription__Endpoint: "${AZUREOPENAI__TRANSCRIPTION__ENDPOINT:-}"
+      AzureOpenAI__Transcription__ApiKey: "${AZUREOPENAI__TRANSCRIPTION__APIKEY:-}"
+      AssemblyAi__ApiKey: "${ASSEMBLYAI__APIKEY:-}"
+      AssemblyAi__EnableBatchPremiumTier: "${ASSEMBLYAI__ENABLEBATCHPREMIUMTIER:-false}"
+      Knowz__CloudProvider__RealtimeTranscription: "${KNOWZ__CLOUDPROVIDER__REALTIMETRANSCRIPTION:-}"
+      Enrichment__FaceRecognition__Enabled: "${ENRICHMENT__FACERECOGNITION__ENABLED:-false}"
+      FaceRecognition__MatchThreshold: "${FACERECOGNITION__MATCHTHRESHOLD:-}"
+
+      # ── AI provider selection (same one-config contract as the api service; empty => offline stub) ──
+      Knowz__CloudProvider: "${KNOWZ__CLOUDPROVIDER:-}"
+      Knowz__CloudProvider__Ai: "${KNOWZ__CLOUDPROVIDER__AI:-}"
+      Knowz__CloudProvider__DocIntelligence: "${KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE:-}"
+      Knowz__CloudProvider__Vision: "${KNOWZ__CLOUDPROVIDER__VISION:-}"
+      Knowz__CloudProvider__Transcription: "${KNOWZ__CLOUDPROVIDER__TRANSCRIPTION:-}"
+      Vertex__Project: "${VERTEX__PROJECT:-}"
+      Vertex__Region: "${VERTEX__REGION:-}"
+      Vertex__ChatModel: "${VERTEX__CHATMODEL:-}"
+      Vertex__EmbeddingModel: "${VERTEX__EMBEDDINGMODEL:-}"
+      Vertex__EmbeddingDimensions: "${VERTEX__EMBEDDINGDIMENSIONS:-1536}"
+      OpenAiCompat__Endpoint: "${OPENAICOMPAT__ENDPOINT:-}"
+      OpenAiCompat__ApiKey: "${OPENAICOMPAT__APIKEY:-}"
+      OpenAiCompat__ChatModel: "${OPENAICOMPAT__CHATMODEL:-}"
+      OpenAiCompat__EmbeddingModel: "${OPENAICOMPAT__EMBEDDINGMODEL:-}"
+      OpenAiCompat__EmbeddingDimensions: "${OPENAICOMPAT__EMBEDDINGDIMENSIONS:-}"
+      GOOGLE_APPLICATION_CREDENTIALS: "${GCLOUD_ADC_PATH:+/gcloud/adc.json}"
+    volumes:
+      # Host ADC at a neutral READ-ONLY path, leaving the well-known path vacant for GCE metadata ADC.
+      # Defaults to /dev/null (inert); set GCLOUD_ADC_PATH to an absolute ADC path for host-file auth.
+      - "${GCLOUD_ADC_PATH:-/dev/null}:/gcloud/adc.json:ro"
+      - knowz-portable-objectsdata:/data/objects
+      - knowz-portable-identity:/var/lib/knowz/identity
+      - knowz-portable-dpkeys:/var/lib/knowz/data-protection-keys
+
+  # ── Web: the SPA (nginx). Runtime /config.js points the browser at the host-mapped API/MCP ports ───
+  web:
+    # Cloud-neutral SPA — plain versioned image (no portable/gcp flavor).
+    image: "${KNOWZ_REGISTRY:-ghcr.io/knowz-io}/knowz-web:${KNOWZ_VERSION:?KNOWZ_VERSION must be set in .env (the platform release, e.g. 0.2.0)}"
+    ports:
+      - "${BIND_ADDRESS:-127.0.0.1}:${WEB_PORT:-3000}:8080"
+    depends_on:
+      api:
+        condition: service_started
+    environment:
+      KNOWZ_API_URL: "${PUBLIC_API_URL:-http://localhost:${API_PORT:-5000}}"
+      KNOWZ_MCP_URL: "${PUBLIC_MCP_URL:-http://localhost:${MCP_PORT:-3001}}"
+    # nginx:alpine has wget, but `localhost` resolves to ::1 (IPv6) while nginx binds
+    # IPv4 — hit 127.0.0.1 explicitly so the probe reaches the listener.
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080/ || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+  # ── MCP: Model Context Protocol server, backed by the portable API ─────────────────────────────────
+  mcp:
+    profiles: ["mcp"]
+    # Cloud-neutral MCP server — plain versioned image (no portable/gcp flavor).
+    image: "${KNOWZ_REGISTRY:-ghcr.io/knowz-io}/knowz-mcp:${KNOWZ_VERSION:?KNOWZ_VERSION must be set in .env (the platform release, e.g. 0.2.0)}"
+    ports:
+      - "${BIND_ADDRESS:-127.0.0.1}:${MCP_PORT:-3001}:8080"
+    depends_on:
+      api:
+        condition: service_healthy
+    environment:
+      ASPNETCORE_URLS: http://+:8080
+      Knowz__BaseUrl: "http://api:8080"
+      MCP__BackendMode: "${MCP_BACKEND_MODE:-selfhosted}"
+      MCP__ApiKeyValidationEndpoint: "${MCP_API_KEY_VALIDATION_ENDPOINT:-/api/vaults}"
+      MCP__ServiceKey: "${MCP_SERVICE_KEY:?MCP_SERVICE_KEY must be set in .env}"
+      Authentication__ValidateApiKey: "${MCP_VALIDATE_API_KEY:-true}"
+    # aspnet:10.0 ships no curl/wget — HTTP readiness probe over bash /dev/tcp (200 on /healthz).
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >-
+          timeout 5 bash -c 'exec 3<>/dev/tcp/127.0.0.1/8080 && printf "GET /healthz HTTP/1.0\r\n\r\n" >&3 && head -1 <&3 | grep -q 200'
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 30s
+
+  public-site:
+    image: "${KNOWZ_REGISTRY:-ghcr.io/knowz-io}/knowz-public-site:${KNOWZ_VERSION:?KNOWZ_VERSION must be set in .env}"
+    profiles: ["public-site"]
+    ports:
+      - "${BIND_ADDRESS:-127.0.0.1}:${PUBLIC_SITE_PORT:-3002}:8080"
+    depends_on:
+      api:
+        condition: service_started
+    environment:
+      KNOWZ_API_URL: "${PUBLIC_API_URL:-http://localhost:${API_PORT:-5000}}"
+      KNOWZ_MCP_URL: "${PUBLIC_MCP_URL:-http://localhost:${MCP_PORT:-3001}}"
+      KNOWZ_PLATFORM_MAIN_APP_URL: "${PUBLIC_WEB_ORIGIN:-http://localhost:${WEB_PORT:-3000}}"
+      KNOWZ_PLATFORM_BASE_DOMAINS: "localhost"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8080/ || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+volumes:
+  knowz-portable-pgdata:
+  knowz-portable-miniodata:
+  knowz-portable-objectsdata:
+  knowz-portable-identity:
+  knowz-portable-dpkeys:

package/assets/portable/postgres-initdb/00-databases-and-extensions.sql

@@ -0,0 +1,16 @@
+-- Portable Postgres bring-up (spec TEST_ComposeProofHarness R4).
+-- Runs once on first cluster init (docker-entrypoint-initdb.d) against the default POSTGRES_DB, via psql.
+-- Creates the platform databases and installs the pgvector (`vector`) + trigram (`pg_trgm`) extensions in
+-- each. The `vector` binary ships in the pgvector/pgvector:pg16 image; `pg_trgm` ships in postgres-contrib.
+-- The API's PortablePostgresSchemaInitializer then EnsureCreates the schema + raw pgvector DDL on first boot.
+
+CREATE DATABASE "KnowzKnowledge";
+CREATE DATABASE "KnowzMaster";
+
+\connect "KnowzKnowledge"
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+\connect "KnowzMaster"
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;

package/assets/portable/releases.json

@@ -0,0 +1,37 @@
+{
+  "releases": [
+    {
+      "version": "0.35.2",
+      "flavors": [
+        "portable",
+        "portable-gcp"
+      ],
+      "releasedAt": "2026-07-30T00:00:00Z",
+      "minCliVersion": null,
+      "notes": null,
+      "digests": null
+    },
+    {
+      "version": "0.33.1",
+      "flavors": [
+        "portable",
+        "portable-gcp"
+      ],
+      "releasedAt": "2026-07-10T00:00:00Z",
+      "minCliVersion": null,
+      "notes": null,
+      "digests": null
+    },
+    {
+      "version": "0.32.0",
+      "flavors": [
+        "portable",
+        "portable-gcp"
+      ],
+      "releasedAt": "2026-07-01T00:00:00Z",
+      "minCliVersion": null,
+      "notes": null,
+      "digests": null
+    }
+  ]
+}

package/assets/portable/runtime-contract.json

@@ -0,0 +1,149 @@
+{
+  "schemaVersion": 1,
+  "contractVersion": "1.4.0",
+  "description": "Management contract for the pull-only Knowz portable container runtime.",
+  "services": [
+    { "id": "api", "required": true, "health": "http" },
+    { "id": "worker", "required": true, "health": "compose-process" },
+    { "id": "web", "required": true, "health": "http" },
+    { "id": "mcp", "required": false, "profile": "mcp", "health": "http" },
+    { "id": "public-site", "required": false, "profile": "public-site", "health": "http" },
+    { "id": "postgres", "required": true, "health": "pg_isready" },
+    { "id": "redis", "required": true, "health": "redis-ping" },
+    { "id": "object-storage", "required": true, "health": "http", "implementations": ["minio", "filesystem"] }
+  ],
+  "imageFlavors": {
+    "default": {
+      "suffix": "",
+      "providers": ["offline", "azure", "knowz-cloud", "openai-compatible"]
+    },
+    "gcp": {
+      "suffix": "-gcp",
+      "providers": ["gcp"]
+    }
+  },
+  "providerAxes": {
+    "master": "KNOWZ__CLOUDPROVIDER",
+    "ai": "KNOWZ__CLOUDPROVIDER__AI",
+    "documentIntelligence": "KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE",
+    "vision": "KNOWZ__CLOUDPROVIDER__VISION",
+    "transcription": "KNOWZ__CLOUDPROVIDER__TRANSCRIPTION",
+    "allowedValues": ["Azure", "Gcp", "OpenAiCompat", "None"]
+  },
+  "licensing": {
+    "activation": "device-code",
+    "mothershipUrlEnvironment": "KNOWZ_LICENSING_MOTHERSHIP_URL",
+    "installCredentialEnvironment": "KNOWZ_LICENSING_INSTALL_CREDENTIAL",
+    "identityVolume": "knowz-portable-identity",
+    "identityMountPath": "/var/lib/knowz/identity",
+    "credentialFile": "credential"
+  },
+  "providerPresets": {
+    "offline": {
+      "imageFlavor": "",
+      "masterProvider": "Azure",
+      "requiredEnvironment": [],
+      "defaults": { "EMBEDDING_PROVIDER": "Stub", "EMBEDDING_DIMENSIONS": "1536" }
+    },
+    "azure": {
+      "imageFlavor": "",
+      "masterProvider": "Azure",
+      "requiredEnvironment": ["AZURE_OPENAI_ENDPOINT", "AZURE_OPENAI_API_KEY"],
+      "defaults": { "EMBEDDING_PROVIDER": "AzureOpenAI", "EMBEDDING_DIMENSIONS": "1536" }
+    },
+    "gcp": {
+      "imageFlavor": "-gcp",
+      "masterProvider": "Gcp",
+      "requiredEnvironment": ["VERTEX__PROJECT", "GCLOUD_ADC_PATH"],
+      "defaults": { "VERTEX__REGION": "us-central1", "EMBEDDING_DIMENSIONS": "1536" }
+    },
+    "openai-compatible": {
+      "imageFlavor": "",
+      "masterProvider": "OpenAiCompat",
+      "requiredEnvironment": [
+        "OPENAICOMPAT__ENDPOINT",
+        "OPENAICOMPAT__CHATMODEL",
+        "OPENAICOMPAT__EMBEDDINGMODEL",
+        "OPENAICOMPAT__EMBEDDINGDIMENSIONS"
+      ],
+      "defaults": { "EMBEDDING_PROVIDER": "OpenAiCompat" }
+    },
+    "knowz-cloud": {
+      "imageFlavor": "",
+      "masterProvider": "OpenAiCompat",
+      "requiredEnvironment": [
+        "OPENAICOMPAT__ENDPOINT",
+        "OPENAICOMPAT__APIKEY",
+        "OPENAICOMPAT__CHATMODEL",
+        "OPENAICOMPAT__EMBEDDINGMODEL",
+        "OPENAICOMPAT__EMBEDDINGDIMENSIONS"
+      ],
+      "defaults": {
+        "OPENAICOMPAT__ENDPOINT": "https://ai.knowz.io/v1",
+        "OPENAICOMPAT__EMBEDDINGDIMENSIONS": "1536",
+        "EMBEDDING_PROVIDER": "OpenAiCompat",
+        "EMBEDDING_DIMENSIONS": "1536"
+      }
+    }
+  },
+  "storageModes": {
+    "minio": {
+      "providerValue": "MinioS3",
+      "persistentVolume": "knowz-portable-miniodata"
+    },
+    "filesystem": {
+      "providerValue": "FileSystem",
+      "rootPath": "/data/objects",
+      "persistentVolume": "knowz-portable-objectsdata"
+    }
+  },
+  "backingServices": {
+    "postgres": {
+      "modes": ["bundled", "external"],
+      "externalOverlay": "docker-compose.external-db.yml",
+      "initOverlay": "docker-compose.external-db-init.yml",
+      "environment": ["PG_HOST", "PG_PORT", "PG_SSL_MODE", "PG_EXTRA_OPTIONS"]
+    },
+    "object-storage": {
+      "modes": ["bundled", "external"],
+      "externalOverlay": "docker-compose.external-storage.yml",
+      "environment": ["S3_ENDPOINT", "S3_REGION", "S3_FORCE_PATH_STYLE"]
+    },
+    "redis": {
+      "modes": ["bundled", "external"],
+      "externalOverlay": "docker-compose.external-redis.yml",
+      "environment": ["REDIS_CONNECTION_STRING"]
+    },
+    "edge": {
+      "modes": ["none", "caddy"],
+      "overlay": "docker-compose.edge.yml"
+    }
+  },
+  "capabilities": {
+    "core-enrichment": { "status": "full", "queues": ["ai-processing", "processing-completed"] },
+    "text-extraction": { "status": "full", "queues": ["text-extraction", "document-intelligence"] },
+    "summarization": { "status": "full", "queues": ["summarization"] },
+    "chunking-indexing": { "status": "full", "queues": ["chunking", "indexing", "search-indexing"] },
+    "vision-transcription": { "status": "full", "queues": ["vision-analysis", "transcription"] },
+    "realtime-progress": { "status": "full", "transport": "worker-api-redis-sse" },
+    "entity-extraction": { "status": "degraded", "behavior": "terminal completion without structured entities" },
+    "face-recognition": { "status": "degraded", "behavior": "job consumed without recognition output" },
+    "graph-sync": { "status": "degraded", "behavior": "job consumed without graph output" },
+    "git-sync": { "status": "unavailable" },
+    "engagement-jobs": { "status": "unavailable" },
+    "ingestion-jobs": { "status": "unavailable" },
+    "sequence-execution": { "status": "unavailable" },
+    "vault-reindex": { "status": "unavailable" },
+    "notification-jobs": { "status": "unavailable" }
+  },
+  "lifecycle": {
+    "composeProjectPrefix": "knowz",
+    "preserveVolumesOnDown": true,
+    "destroyRequiresConfirmation": true,
+    "defaultBindAddress": "127.0.0.1",
+    "infrastructureHostPortsPublished": false,
+    "publicUrlEnvironment": ["PUBLIC_API_URL", "PUBLIC_WEB_ORIGIN", "PUBLIC_MCP_URL", "PUBLIC_SITE_URL"],
+    "upgradeStrategy": "pull-and-reapply",
+    "rollbackSupported": false
+  }
+}

package/bin/run.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execute } from '@oclif/core';
+
+await execute({ dir: import.meta.url });