minutework 0.1.39 → 0.1.40

package/assets/claude-local/skills/README.md

@@ -47,6 +47,7 @@ Generated-workspace-first guidance should live here, especially:
 - `workspace-guidance-refresh/SKILL.md`
 - `shell-architecture/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`
+- `integration-broker-and-connectors/SKILL.md`
 - `layering-and-import-modes/SKILL.md`
 - `standalone-mobile-client/SKILL.md`
 - `capability-gap-reporting/SKILL.md`

package/assets/claude-local/skills/ai-capability-defaults/SKILL.md

@@ -14,6 +14,9 @@ generation, itinerary generation, content generation, or structured-output UX.
 - `tenant-app` should gather inputs, invoke typed platform/runtime surfaces, and
   display or edit outputs; do not embed provider credentials or direct
   browser-to-model calls in the web app for MVP.
+- When AI agents need to drive external providers such as ads, also read
+  `integration-broker-and-connectors/SKILL.md` and use the governed connector
+  capability instead of browser or sidecar provider calls.
 - Do not create a bespoke `sidecar` for drafting/generation unless the existing
   runtime AI capability has a concrete gap or there is another backend-only
   requirement.

package/assets/claude-local/skills/integration-broker-and-connectors/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: integration-broker-and-connectors
+description: "External integrations, ads, brokered connectors, spend/approval governance, or whether to use mw.connector.ads instead of bespoke provider code."
+---
+
+# Integration Broker And Connectors
+
+Use this skill when a request touches external integrations, paid acquisition,
+ads, provider connectors, agent-driven provider actions, spend limits,
+approvals, credentials, receipts, or questions like "can the agent run ads?"
+
+## What It Is
+
+MinuteWork has a governed integration broker for external systems. The first
+native connector is `mw.connector.ads`.
+
+- Runtime owns the local action surface and exposes connector actions as
+  `workflow.run_action` capability calls.
+- Platform DJ owns provider credentials, provider account scope, tenant broker
+  connections, advertiser identity, spend authorization, approval policy,
+  append-only receipts, webhooks, and adapter execution.
+- Generated apps and sidecars should call the brokered capability instead of
+  storing provider credentials or implementing ad-spend policy locally.
+- Provider availability still depends on configured platform broker accounts.
+  Do not promise a provider is live just because a provider key is reserved.
+
+## Compose, Do Not Rebuild
+
+Before adding ad, spend, approval, credential, or connector logic to
+`tenant-app` or a `sidecar`, check whether the integration belongs on the
+broker path.
+
+- Use `integration_broker.execute` for brokered connector actions.
+- Use `mw.connector.ads` for ads instead of inventing tenant-local ad APIs.
+- Add providers through the platform broker adapter seam, not browser code,
+  generated app credentials, or ungoverned sidecar calls.
+- Keep provider account and organization scope in Platform DJ. Tenant payloads
+  must not supply provider account, ad account, organization, or credential
+  identifiers as a way to bypass the broker connection.
+- Use app-pack or schema changes for tenant product data around the integration,
+  but keep external provider writes on the governed broker.
+
+## Ads Connector
+
+`mw.connector.ads` is a first-party runtime app-pack baseline. It is available
+without a tenant app installing an ads pack.
+
+Mutating actions:
+
+- `ads.create_campaign`
+- `ads.update_campaign`
+- `ads.pause_campaign`
+- `ads.create_group`
+- `ads.create_creative`
+- `ads.create_ad`
+
+Read action:
+
+- `ads.fetch_report`
+
+Reserved future action:
+
+- `ads.record_conversion`
+
+Provider keys:
+
+- Default: `openaiads`
+- Extensible: `googleads`, `metaads`, `tiktokads`
+
+Treat these provider keys as broker-routing keys. Do not infer that a provider
+is configured for a tenant until the runtime capability inventory or platform
+broker preflight reports readiness.
+
+## Governance Model
+
+Rely on the broker safety model instead of recreating it:
+
+- `BrokerProviderAccount` and `BrokerConnection` bind platform-owned provider
+  account scope to tenant broker access.
+- `AdvertiserProfile` represents verified advertiser identity and accepted
+  terms.
+- `AdsSpendAuthorization` defines approved spend caps.
+- `AdsSpendPolicyReceipt` records reserved/released budget decisions.
+- `TenantWallet.reserved_credits_cents` backs approved future ad spend before
+  more metered work can consume the same credits.
+- `BrokerApprovalGrant` gates mutating/spend actions with human approval.
+- `BrokerReceipt` and `BrokerWebhookEvent` provide append-only, payload-digested
+  audit trails.
+- `AdsCampaignProjection` and `AdsObjectProjection` project provider objects
+  back into scoped tenant/runtime state.
+
+Mutating ads actions are approval-gated and budget-gated. Credentials and spend
+policy never belong in browser code, generated app artifacts, or tenant-local
+sidecar configuration.
+
+## Builder Decision Rules
+
+- For paid-acquisition or ads questions, route through this skill before
+  proposing a custom ad manager.
+- For "what can we build?" answers, mention that runtime agents can drive
+  governed external integrations when a first-party or broker-backed connector
+  exists.
+- For AI-agent workflows, keep AI and provider actions inside governed runtime
+  capabilities. UI gathers intent and renders results.
+- For OSS or mature external products, use `attached_app` or sidecar bridge code
+  only when the foreign system should remain foreign. Connector writes still
+  need broker-style governance when credentials, spend, approvals, or audit are
+  involved.
+- If a requested connector is missing, report a platform capability gap instead
+  of adding unreviewed provider credentials or a direct network adapter.
+
+Useful inspection points when source is available:
+
+- `apps/mwv3-platform-dj/apps/integration_broker/models.py`
+- `apps/mwv3-platform-dj/apps/integration_broker/services.py`
+- `apps/mwv3-platform-dj/apps/integration_broker/adapters.py`
+- `apps/mwv3-platform-dj/apps/integration_broker/api/`
+- `apps/mwv3-runtime-dj/apps/runtime_app_host/first_party_packs/mw_connector_ads.py`
+- `apps/mwv3-runtime-dj/apps/runtime_app_host/ads_connector_services.py`
+- `apps/mwv3-runtime-dj/apps/runtime_app_host/integration_broker_capabilities.py`
+- `reference/mwv3-dj6-docs/connector_pack_and_engine_resolution_contract.md`
+- `reference/mwv3-dj6-docs/runtime_app_pack_contract.md`

package/assets/claude-local/skills/layering-and-import-modes/SKILL.md

@@ -16,6 +16,10 @@ Use this skill when choosing between configuration, app-pack changes, overlays,
   or composition inside the Builder sandbox.
 - Durable tenant behavior should usually compile to governed app-pack artifacts,
   not ad hoc backend code.
+- For external integrations that involve credentials, provider writes, spend,
+  approvals, or audit receipts, read
+  `integration-broker-and-connectors/SKILL.md` and use the broker substrate when
+  it fits.
 - Use `attached_app` when a mature foreign system should remain its own
   subsystem and MinuteWork should compile a governed control surface around it.
 - Use `external_repo_intake` only when no reviewed capability skill or cleaner

package/assets/claude-local/skills/project-overview-and-strategy/SKILL.md

@@ -31,6 +31,9 @@ needed:
   belongs in governed runtime capabilities instead of browser/provider calls.
 - `layering-and-import-modes/SKILL.md` for build-native vs govern-existing,
   `attached_app`, OSS adoption, and greenfield-last decisions.
+- `integration-broker-and-connectors/SKILL.md` for external integrations, paid
+  acquisition, ads, brokered connectors, spend/approval governance, and
+  `mw.connector.ads`.
 - `sidecar-generation/SKILL.md` for bridge/integration execution, workers,
   webhooks, schedulers, and backend compute.
 - `standalone-mobile-client/SKILL.md` for Expo/native client boundaries.
@@ -87,6 +90,9 @@ substrate:
 - Runtime agents use `mw.runtime.agent` seed records and namespaced runtime-kind
   tool packs. UI surfaces collect inputs and render governed outputs; they do
   not run model/provider logic directly.
+- Runtime agents can drive external integrations through governed connector
+  capabilities such as `mw.connector.ads`; credentials, spend approvals, and
+  provider writes stay brokered by the platform.
 - OSS and mature external products are adopted before rebuilding when they fit.
   Use `attached_app` when the foreign system should remain independently
   deployed, and use sidecar bridge code plus runtime agents/tool packs to make

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutework",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "MinuteWork CLI for workspace scaffolding, local preview workflows, and hosted preview deploys.",
   "type": "module",
   "bin": {
@@ -24,8 +24,8 @@
     "@modelcontextprotocol/sdk": "^1.28.0",
     "jiti": "^2.6.1",
     "zod": "^4.3.6",
-    "@minutework/platform-config": "0.1.2",
-    "@minutework/schema-compiler": "0.1.5"
+    "@minutework/schema-compiler": "0.1.5",
+    "@minutework/platform-config": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",