minutework 0.1.52 → 0.1.54

package/README.md

@@ -147,7 +147,7 @@ minutework deploy --preview
 
 Combined **tenant-app + sidecar** workspaces keep sidecar setup explicit. Root `pnpm install` stays Node-only and does not run `poetry install` for you. If you need the sidecar, run `pnpm run install:sidecar` from the workspace root or `cd sidecar && poetry install` yourself before `minutework dev` or `minutework test`. Sidecar-only scaffolds have no root `package.json`; install Python deps once inside `sidecar/` before running local sidecar workflows.
 
-For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Vercel, point the project Root Directory at `tenant-app`; the optional sidecar remains a separate Poetry-managed surface. To keep `@minutework/web-auth` same-origin on a bring-your-own host, set `MW_GATEWAY_BASE_URL` to the platform gateway base URL — the template's `next.config.mjs` then proxies `/_mw/*` to the gateway — and run `minutework deploy --live --host <your-domain>` so the gateway recognizes that host as your tenant's live canonical customer-web origin.
+For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Vercel, point the project Root Directory at `tenant-app`; the optional sidecar remains a separate Poetry-managed surface. To keep `@minutework/web-auth` same-origin on a bring-your-own host, set `MW_GATEWAY_BASE_URL` to the canonical live customer-web host returned by `minutework deploy --live` — the template's `next.config.mjs` then proxies `/_mw/*` to the gateway — and run `minutework deploy --live --host <your-domain>` so the gateway recognizes that host as your tenant's live canonical customer-web origin. For local auth against dev, target `https://dev.minutework.ai`, deploy live there, then set `MW_GATEWAY_BASE_URL` to the returned `https://<label>.customers.dev.minutework.ai` host, not bare `https://dev.minutework.ai`.
 
 `link` provisions or resolves the default published-site property for the active tenant and stores that property key in repo-local state. The SDK-based `tenant-app/.env.example` contains only the app metadata contract used by the template: `NEXT_PUBLIC_MW_APP_ID`, `MW_TEMPLATE_APP_NAME`, and optional `MW_PUBLIC_BASE_URL`. Browser auth and manifest calls use same-origin `/_mw` routes through `@minutework/web-auth`; do not add platform content tokens or public-site property vars to the tenant app.
 

package/assets/claude-local/skills/ontology-authoring/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ontology-authoring
+description: "Promoting a local fact to shared, URN-anchored truth: declaring ontology mappings, URN anchors, and promotion rules, then staging reviewable promotion candidates."
+---
+
+# Ontology Authoring
+
+Use this skill when a local app object should become — or resolve to — a
+**shared, Core-owned, URN-anchored** entity that other tenants' runtimes can
+recognize. This is the authoring half of the promotion loop; the
+principles-only companion is `ontology-mapping/SKILL.md`.
+
+The review law is the point of this lane:
+**Core is the sole `urn:mw:<kind>:<uuid>` minter; a runtime never mints, and
+every promotion is reviewable.** You stage a candidate locally and the
+bridge-owned sweep submits it; an operator (or the conservative auto-accept)
+decides. Nothing you author activates a shared URN by itself.
+
+## 1. Classify: shared WHO/WHERE/WHAT vs tenant-local
+
+Decide, per object, whether it is genuinely shared identity or just tenant
+data:
+
+- `entity` — a shared **WHAT/WHO-org** (a company, vendor, carrier, account).
+- `person` — a shared **WHO** (PII-bearing; always operator-reviewed).
+- `location` — a shared **WHERE** (always operator-reviewed).
+- Everything high-variance or tenant-specific stays **runtime-local** — do not
+  promote it. Overlay it instead (step 2).
+
+Map the object's stable identifiers to namespaced identifier types
+(`EntityIdentifier.id_type` for entities, `PersonIdentifier.id_type` for
+persons). A good shared identifier is namespaced and externally meaningful
+(e.g. a government registry number). FleetRun is illustrative only: a carrier's
+DOT number is an `entity` identifier; the carrier's internal nickname is not.
+
+## 2. Declare mappings, anchors, and overlays (schema DSL)
+
+In `schemas/schema.ts` (or `schema.mw`), declare `ontologyMappings`:
+
+```ts
+ontologyMapping("vendor", "entity", {
+  anchors: [anchor("entity_ref", "entity")],
+  promotionRules: [
+    promotionRule("entity_ref", "entity", {
+      mode: "candidate_match",
+      idType: "registry_id",
+      minConfidence: 0.95,
+    }),
+  ],
+  overlays: [overlay("entity_ref", "vendor_terms", ["payment_terms", "rep"])],
+})
+```
+
+- `anchor(field, target_kind)` — the local field that carries the shared URN
+  once resolved. Compiles into a `URNAnchor` target.
+- `overlay(target_urn_field, overlay_kind, payload_fields)` — hang
+  tenant-specific fields off a shared entity **without** mutating the shared
+  baseline. Keep high-variance fields here, not in the shared object.
+- These compile to `ontologyMappingManifests`, which the runtime materializes
+  as `LocalOntologyMapping` rows on install — that is what makes this runtime's
+  objects of the kind promotion-eligible and what `ontology.resolve_local`
+  falls back to.
+
+## 3. Declare promotion rules (`prom_v1`)
+
+For a promotable fact, declare a `promotionRule` with:
+
+- `mode`: `candidate_match` (resolve to an existing shared entity) or
+  `candidate_create` (propose a new one).
+- `id_type`: the namespaced identifier the match keys on.
+- `min_confidence` (optional): the floor for the conservative entity
+  auto-accept. **Auto-accept fires only for `entity`, only on an exactly-one
+  unique-identifier match at confidence ≥ threshold, and only as an echo of the
+  existing URN — no mint, no create, no merge.** Person, location, zero/multi
+  matches, and any create/merge always go to operator review.
+
+## 4. Stage a candidate at runtime (staging only)
+
+Staging is a runtime act, separate from submission. Cite the exact tools (both
+are outside the default read ring — grant per agent via `enable_agent_tools`):
+
+- `ontology.resolve_local` — read, live. Returns the `URNAnchor` for a local
+  object (the shared `core_urn`) or the active mapping candidates as fallback.
+- `ontology.propose_candidate` — effectful, **staging only**. Records a PENDING
+  `PromotionCandidate`; it does **not** push to Core. The bridge-owned sweep
+  (`MW_ONTOLOGY_PROMOTION_REPORTING_ENABLED`) submits, and Core decides.
+
+Provenance is mandatory and you never supply a URN:
+
+- Put namespaced identifiers in `evidence.identifiers`
+  (`[{ id_type, value }]`), the local anchor target in `evidence.anchor`
+  (`{ local_object_kind, local_object_id, field_name }`), and the supporting
+  signal as plain `evidence` keys.
+- Pass a calibrated `confidence` and an opaque `source_ref` (a
+  `runtime:<id>:<kind>:<id>` reference) — never a `urn:mw:` value, and never a
+  `core_urn`. Only Core mints URNs.
+
+## Cross-runtime anchoring
+
+A runtime learns a shared `core_urn` **only for facts it itself staged**. There
+is no open "does identifier X exist in Core" lookup. When a second runtime has
+the same mapping installed and stages its own candidate for the same fact, the
+sweep re-POSTs it, Core's `(origin_runtime, origin_ref, candidate_kind)` unique
+constraint dedupes against the already-decided request and returns the **same**
+`core_urn`, and that runtime writes its own `URNAnchor`. Same shared truth, no
+new trust surface.
+
+## Cross-references
+
+- `runtime_ontology_contract.md` — runtime-local anchors, mappings, candidates.
+- `core_ontology_and_runtime_overlays.md` — Core ownership and overlays.
+- `schema-engine/SKILL.md` — declaring the schema the mappings hang off.
+- `app-pack-authoring/SKILL.md` — packaging the mappings into an installable app.
+- `ontology-mapping/SKILL.md` — the principles companion.

package/assets/claude-local/skills/ontology-mapping/SKILL.md

@@ -8,6 +8,10 @@ description: "Local app data needs shared identifiers, shared meaning, or mappin
 Use ontology mappings when local app data needs shared identifiers or shared
 meaning.
 
+For the concrete authoring procedure (declaring mappings, URN anchors, and
+promotion rules, then staging reviewable promotion candidates), see the sibling
+`ontology-authoring/SKILL.md`.
+
 - Prefer stable shared references and URNs over duplicating shared entities.
 - Runtime should remain ontology-aware, not ontology-authoritative.
 - Keep local app schema ownership clear even when mapping into shared ontology

package/assets/claude-local/skills/runtime-capability-inventory/SKILL.md

@@ -142,6 +142,12 @@ generated Builder workspace.
   - `ontology.resolve_local` -- Read-only native tool over
     URNAnchor/LocalOntologyMapping; not in the default READ_RING, granted per agent via
     enable_agent_tools.
+  - `ontology.propose_candidate` -- Stages a PENDING PromotionCandidate locally
+    (idempotent on origin_ref+candidate_kind). The bridge-owned submission sweep then
+    carries it cross-plane (PENDING -> SUBMITTED -> resolved with a Core-minted
+    core_urn) under MW_ONTOLOGY_PROMOTION_REPORTING_ENABLED; Core stays the sole URN
+    minter and its ingress fails closed independently. Effectful; outside the default
+    READ_RING, granted per agent via enable_agent_tools.
   - `command_exec.run_template` -- Operator/platform-dispatch surface; not an
     agent-callable tool.
   - `voice.hangup_call` -- VoiceSession finalization is live; the provider-side hangup
@@ -152,12 +158,6 @@ generated Builder workspace.
   leg as unavailable):
   - `scheduling.book_appointment` -- Capability is registered but the direct booking
     executor is MVP-deferred; preflight truthfully reports provider_unavailable.
-  - `ontology.propose_candidate` -- Staging leg only: records a PENDING
-    PromotionCandidate locally (idempotent on origin_ref+candidate_kind). The
-    cross-plane submission to Core (PENDING -> SUBMITTED -> resolved with a minted
-    core_urn) is a deferred, bridge-owned leg; the promotion service stays
-    platform-owned. Effectful; outside the default READ_RING, granted per agent via
-    enable_agent_tools.
   - `voice.initiate_call` -- Pre-dial stack is live (consent + TCPA preflight, approval
     parking, VoiceSession lifecycle); the Twilio dial + realtime media worker are
     platform-owned Phase 4.

package/assets/claude-local/skills/runtime-capability-inventory/primitive-catalog.json

@@ -304,9 +304,9 @@
       "requires_integration": false,
       "requires_secret": false,
       "metered": false,
-      "executor_ready": "partial",
+      "executor_ready": "live",
       "executor_ref": "tool:ontology.propose_candidate",
-      "executor_notes": "Staging leg only: records a PENDING PromotionCandidate locally (idempotent on origin_ref+candidate_kind). The cross-plane submission to Core (PENDING -> SUBMITTED -> resolved with a minted core_urn) is a deferred, bridge-owned leg; the promotion service stays platform-owned. Effectful; outside the default READ_RING, granted per agent via enable_agent_tools.",
+      "executor_notes": "Stages a PENDING PromotionCandidate locally (idempotent on origin_ref+candidate_kind). The bridge-owned submission sweep then carries it cross-plane (PENDING -> SUBMITTED -> resolved with a Core-minted core_urn) under MW_ONTOLOGY_PROMOTION_REPORTING_ENABLED; Core stays the sole URN minter and its ingress fails closed independently. Effectful; outside the default READ_RING, granted per agent via enable_agent_tools.",
       "agent_exposable": true,
       "agent_exposure_path": "native_tool",
       "approval_required": false,

package/assets/claude-local/skills/schema-engine/SKILL.md

@@ -9,6 +9,9 @@ Use this skill when the request needs tenant-defined data structures.
 
 - Define tenant data in `schemas/schema.ts` or `schema.mw`, not ad hoc Django tables.
 - Prefer declarative schema changes before adding custom code surfaces.
+- To map local objects onto shared, URN-anchored ontology entities, declare
+  `ontologyMappings` (with `anchor`, `promotionRule`, and `overlay` helpers) in
+  the same schema source; the procedure is in `ontology-authoring/SKILL.md`.
 - Index only the fields that need query/filter behavior.
 - Treat runtime-backed content as the authoring source; publish safe snapshots for anonymous public delivery.
 - Treat `mw.core.site` as already present in the runtime baseline.

package/assets/claude-local/skills/tenant-app-customer-auth-deploy/SKILL.md

@@ -55,6 +55,14 @@ unattended; without `--yes` it returns `confirmation_required`).
   activate. On a BYO host, set `MW_GATEWAY_BASE_URL` in the tenant-app so the
   template's `next.config.mjs` proxies same-origin `/_mw/*` to the gateway
   (managed-subdomain hosts are gateway-fronted and need no rewrite).
+- **Local tenant-app against the dev platform:** target the dev platform
+  explicitly (`export MW_CLI_PLATFORM_BASE_URL=https://dev.minutework.ai` and
+  `minutework login --platform https://dev.minutework.ai`), link a sandbox
+  runtime, then run `minutework deploy --live`. Set `tenant-app/.env.local`
+  `MW_GATEWAY_BASE_URL` to the returned canonical live customer-web host such as
+  `https://<label>.customers.dev.minutework.ai` before running local `next dev`.
+  Do not set it to bare `https://dev.minutework.ai`; the gateway resolves
+  `/_mw` customer auth by the live customer-web host.
 
 ## Boundaries and current limits
 

package/assets/templates/next-tenant-app/.env.example

@@ -1,7 +1,9 @@
 NEXT_PUBLIC_MW_APP_ID=tenant.app
 MW_TEMPLATE_APP_NAME=Tenant App
 MW_PUBLIC_BASE_URL=
-# Only needed when hosting this app off-platform (Vercel / custom domain). Set to the
-# MinuteWork platform gateway base URL to transparently proxy same-origin /_mw/* customer
-# auth to the gateway. Leave blank for managed-subdomain hosts (gateway-fronted).
+# Only needed when hosting this app off-platform (Vercel / custom domain) or
+# running local next dev against a live customer-web binding. Set this to the
+# canonical live customer-web host returned by `minutework deploy --live`, such as
+# https://<label>.customers.dev.minutework.ai. Do not set it to bare
+# https://dev.minutework.ai.
 MW_GATEWAY_BASE_URL=

package/assets/templates/next-tenant-app/README.md

@@ -64,6 +64,21 @@ runtime-command demo, or a server-only public-content token adapter.
   defaults to `tenant.app`
 - `MW_TEMPLATE_APP_NAME` controls the display name and defaults to `Tenant App`
 - `MW_PUBLIC_BASE_URL` is optional and only affects metadata routes
+- `MW_GATEWAY_BASE_URL` is only needed when the app is not directly
+  gateway-fronted. For local auth against dev, set it to the canonical live
+  customer-web host returned by `minutework deploy --live`, for example
+  `https://<label>.customers.dev.minutework.ai`. Do not set it to bare
+  `https://dev.minutework.ai`; `/_mw` auth is resolved from the live
+  customer-web host.
+
+Local real-auth dev loop:
+
+1. `export MW_CLI_PLATFORM_BASE_URL=https://dev.minutework.ai`
+2. `minutework login --platform https://dev.minutework.ai`
+3. `minutework link --runtime --sandbox`
+4. `minutework deploy --live`
+5. set `MW_GATEWAY_BASE_URL` to the returned `*.customers.dev.minutework.ai`
+   live host, then run local `next dev`.
 
 ## Validation
 

package/assets/templates/next-tenant-app/next.config.mjs

@@ -22,11 +22,11 @@ function resolveTurbopackRoot(startDirectory) {
 
 // Bring-your-own host support: when this tenant-app is hosted off-platform (Vercel
 // or a custom domain) instead of being fronted by the MinuteWork gateway, set
-// MW_GATEWAY_BASE_URL so same-origin `/_mw/*` customer-auth calls are transparently
-// proxied to the platform gateway. The gateway serves customer auth for this tenant's
-// live canonical customer-web host (provisioned via `minutework deploy --live`), so
-// @minutework/web-auth keeps its same-origin contract without a remote project URL.
-// Unset by default: managed-subdomain hosts are gateway-fronted and need no rewrite.
+// MW_GATEWAY_BASE_URL to the live canonical customer-web host returned by
+// `minutework deploy --live`. The gateway serves customer auth only for that
+// host, so local dev should point at e.g. https://<label>.customers.dev.minutework.ai,
+// not the bare platform origin. Unset by default: managed-subdomain hosts are
+// gateway-fronted and need no rewrite.
 const gatewayBaseUrl = (process.env.MW_GATEWAY_BASE_URL || "").trim().replace(/\/+$/, "");
 
 const nextConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutework",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "MinuteWork CLI for workspace scaffolding, local preview workflows, and hosted preview deploys.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "jiti": "^2.6.1",
     "zod": "^4.3.6",
     "@minutework/platform-config": "0.1.3",
-    "@minutework/schema-compiler": "0.1.12"
+    "@minutework/schema-compiler": "0.1.13"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",