minutework 0.1.55 → 0.1.57

package/assets/claude-local/CLAUDE.md.template

@@ -73,6 +73,25 @@ When the task involves event-driven behavior or reacting to external/reference
 datasets, read `skills/event-bus/SKILL.md` and
 `skills/cross-server-subscriptions/SKILL.md`.
 
+## Authored Workspace Overlays
+
+Everything under `skills/` plus `CLAUDE.md` and `AGENTS.md` is **managed**:
+`minutework workspace sync-assets` regenerates it from the MinuteWork baseline.
+This workspace may also carry **authored overlays** that capture intent specific
+to this build and are **never** overwritten by sync:
+
+- `CLAUDE.workspace.md` / `AGENTS.workspace.md` — authored guidance. Read the one
+  your engine uses (`CLAUDE.workspace.md` in Claude Code; `AGENTS.workspace.md`
+  in Codex/Cursor/other agents). They typically mirror each other.
+- `skills.workspace/<name>/SKILL.md` — authored skills. Browse this directory the
+  same way you browse `skills/`, and read a `SKILL.md` when its topic matches.
+
+When an authored overlay and the managed baseline disagree for this workspace,
+the authored overlay wins — it was written for this specific product. Treat the
+overlays as your own to edit; do not move authored content into the managed
+`CLAUDE.md`, `AGENTS.md`, or `skills/` files, because the next
+`minutework workspace sync-assets` would discard it.
+
 ## Capability Gaps
 
 When a request exposes missing shared MinuteWork substrate, read

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

@@ -54,6 +54,8 @@ Generated-workspace-first guidance should live here, especially:
 - `vuilder-workspace-architecture/SKILL.md`
 - `vuilder-public-site-authoring/SKILL.md`
 - `vuilder-mode-b-hosted-and-spawn/SKILL.md`
+- `visualize-context/SKILL.md`
+- `landing-page-assets/SKILL.md`
 - `workspace-guidance-refresh/SKILL.md`
 - `shell-architecture/SKILL.md`
 - `runtime-capability-inventory/SKILL.md`

package/assets/claude-local/skills/landing-page-assets/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: landing-page-assets
+description: "Generate website-ready hero images, backgrounds, section visuals, textures, and OG assets, then wire selected images into public-site surfaces."
+---
+
+# Landing Page Assets
+
+Use this skill when the user asks for website-bound imagery, for example:
+
+- "generate hero image"
+- "background image"
+- "section below it"
+- "website asset"
+- "landing page visual"
+- "use this in the site"
+- "OG image"
+- "texture"
+
+Default v1 output: generate an actual image, store it, add alt text, and wire
+the selected asset into the target site/page/manifest when a target surface is
+available.
+
+## Asset Roles
+
+Choose one role before prompting:
+
+- `hero_background`: wide atmospheric or metaphor image behind/around HTML text.
+- `hero_visual`: primary product/domain visual next to or within the hero.
+- `section_illustration`: visual supporting a feature/content section.
+- `background_texture`: text-free repeatable or full-bleed texture/motif.
+- `cta_visual`: closing section image that reinforces action.
+- `og_image`: social preview image; text is allowed only when explicitly needed.
+
+Strong rule: prefer HTML text over text baked into images. Only generate a
+poster/graphic with text when the user explicitly asks for a graphic image or
+OG card.
+
+## Workflow
+
+1. Infer the asset role and target section.
+   - Use the latest user request, current page JSON, section id, and prior
+     visual direction.
+   - If a target page/manifest is available, note where the asset should land.
+   - If the user only wants exploration, generate a preview artifact and do not
+     mutate the site.
+
+2. Preserve brand and layout inputs.
+   - Keep palette, typography mood, material style, photo/illustration style,
+     and metaphor constraints.
+   - For verticals like trucking, healthcare, legal, or finance, use grounded
+     domain visuals and avoid generic SaaS abstractions.
+
+3. Write an asset prompt.
+   - Include role, section purpose, subject, composition, palette, lighting,
+     texture, crop safety, responsive layout intent, and negative constraints.
+   - For backgrounds, explicitly request no text, no UI, no logos, and safe
+     empty space where page HTML will sit.
+   - For section images, avoid fake product screenshots unless the user asks
+     for an interface mockup.
+
+4. Generate through `media.generate_image`.
+   - `use_case`: `landing_page_asset`.
+   - Use 16:9 or 21:9 for hero/backgrounds, 4:3 for section visuals, and
+     1200x630 for OG images.
+   - Attach generated outputs to the thread for preview.
+
+5. Promote the selected asset when it belongs in a public site.
+   - Use the public-dj media asset upsert endpoint/service to create or update
+     `MediaAsset` by `vertical + asset_key`.
+   - Store durable metadata: `asset_key`, `digest`, `url`, `alt_text`, `role`,
+     dimensions, mime type, and prompt summary.
+   - Do not store long-lived presigned URLs or storage secrets in manifest
+     metadata.
+
+6. Wire the page/manifest.
+   - Add or update manifest `payload.media[]` entries:
+
+```json
+{
+  "asset_key": "fleet-hero-owner-operator",
+  "digest": "sha256:...",
+  "url": "/api/v1/media/fleetrun/fleet-hero-owner-operator/sha256:...",
+  "alt_text": "Owner-operator reviewing an insurance quote beside a semi truck",
+  "role": "hero_background",
+  "metadata": {
+    "width": 1600,
+    "height": 900,
+    "mime_type": "image/png"
+  }
+}
+```
+
+   - In section payloads, reference images by `asset_key` when possible:
+
+```json
+{
+  "type": "hero_with_cta",
+  "headline": "Instant quote. Instant answers.",
+  "image": {
+    "asset_key": "fleet-hero-owner-operator",
+    "role": "hero_background"
+  }
+}
+```
+
+   - Supported section image fields for v1:
+     `hero_with_cta.image`, `feature_grid.items[].image`,
+     `content_markdown.image`, and `cta_banner.image`.
+   - For workspace-only generated assets, place selected files under the
+     site's public asset directory and reference them directly.
+
+## Prompt Patterns
+
+Hero/background:
+
+```text
+Create a website hero_background for [product/page] serving [audience].
+Subject: [domain-specific scene or metaphor].
+Composition: wide crop, responsive-safe, clear negative space for HTML text on [side].
+Style: [brand style, palette, lighting, realism level].
+No text, no UI, no logos, no fake brand marks.
+Aspect ratio: 16:9 or 21:9.
+```
+
+Section visual:
+
+```text
+Create a section_illustration for the section "[section headline]".
+Show [specific concept/user/workflow] in a grounded way.
+Composition: uncluttered, works beside HTML text, no tiny labels.
+Style: [brand cues].
+Avoid generic SaaS dashboards unless a product UI is explicitly requested.
+```
+
+OG image:
+
+```text
+Create an og_image for [product/page].
+Use the brand/product as the first-viewport signal.
+Readable text only if explicitly requested; otherwise leave text to HTML/social metadata.
+Aspect ratio: 1200x630.
+```
+
+## Guardrails
+
+- Do not bake landing page body copy into imagery.
+- Do not generate fake customer logos, certifications, insurance carrier logos,
+  DOT records, prices, or legal/compliance claims.
+- Do not use dark, blurred, cropped, stock-like imagery when the asset needs to
+  communicate the actual product, buyer, or domain.
+- Do not promote an asset into a site unless the user asked to use it or the
+  current task is site generation.
+- Always provide alt text for promoted assets.

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

@@ -135,6 +135,9 @@ generated Builder workspace.
     action capability; preflight fail-closes on connection/secret availability, and the
     delivery row is idempotent on the ActionRun id with a SENT short-circuit. Not
     agent-exposed yet: exposure is a separate per-definition mw.core.agent_actions flip.
+  - `media.generate_image` -- Runtime media action capability wraps the existing
+    generate_image service, stores outputs in runtime_storage, and attaches
+    generated_image thread artifacts when thread context is present.
   - `consent.check_channel` -- Service seam consumed by other executors and sidecars as
     a preflight; not an agent-callable tool.
   - `discovery.request_proposal` -- Effectful; outside the default READ_RING, granted

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

@@ -217,6 +217,25 @@
       "approval_required": false,
       "interim_path": ""
     },
+    {
+      "primitive_id": "media.generate_image",
+      "family": "media",
+      "display_name": "Generate Image",
+      "description": "Generate image assets through the runtime media provider and store outputs as runtime files.",
+      "runtime_app": "runtime_media",
+      "dispatch_path": "",
+      "status": "active",
+      "requires_integration": false,
+      "requires_secret": true,
+      "metered": true,
+      "executor_ready": "live",
+      "executor_ref": "capability:media.generate_image",
+      "executor_notes": "Runtime media action capability wraps the existing generate_image service, stores outputs in runtime_storage, and attaches generated_image thread artifacts when thread context is present.",
+      "agent_exposable": true,
+      "agent_exposure_path": "app_pack_action",
+      "approval_required": false,
+      "interim_path": ""
+    },
     {
       "primitive_id": "consent.check_channel",
       "family": "consent",

package/assets/claude-local/skills/visualize-context/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: visualize-context
+description: "Generate strategy, product, system, PLG, and concept visuals from messy context, then attach generated images to the Builder thread."
+---
+
+# Visualize Context
+
+Use this skill when the user asks to visualize strategy/product context, for
+example:
+
+- "visualize this"
+- "generate an image"
+- "show the flow"
+- "make this easier to see"
+- "PLG loop"
+- "system map"
+- "architecture visual"
+- "background metaphor"
+
+Default v1 output: an actual generated image attached back to the thread as a
+runtime-stored `generated_image` artifact. Do not stop at a prompt unless image
+generation is unavailable.
+
+## Workflow
+
+1. Extract the decision context.
+   - Identify the product, audience, buyer, loop, system, or strategic argument.
+   - Preserve named entities, constraints, data flow, and any stated design style.
+   - Separate verified facts from interpretation. Do not invent traction,
+     customers, logos, certifications, or claims.
+
+2. Choose the visual type.
+   - `product_flow_map`: activation, value moment, retention, conversion.
+   - `plg_loop`: acquisition, free value, habit, share/expand, conversion.
+   - `system_diagram`: components, data movement, approvals, runtime boundaries.
+   - `strategy_map`: thesis, unfair advantage, risks, market timing, proof.
+   - `concept_visual`: metaphor image that makes an abstract idea graspable.
+   - `landing_hero_mockup`: first-screen marketing visual preview only. If the
+     user wants assets used in a site, switch to `landing-page-assets`.
+
+3. Write a structured image prompt.
+   - Put the core visual in the first sentence.
+   - Include layout, hierarchy, style, palette, target aspect ratio, and what
+     should be legible.
+   - Use labels sparingly. Prefer large, readable labels over dense tiny text.
+   - If the image is meant to explain a complex flow, ask for a clean diagram
+     composition, not a photorealistic scene.
+
+4. Generate through `media.generate_image`.
+   - Use `use_case`: `visualize_context`.
+   - Use 16:9 or 4:3 for strategy diagrams; 1:1 only when the user asks for a
+     square artifact.
+   - Set `request_source_ref` to the current thread/run context when available.
+   - Attach the generated output as a thread artifact. The action capability
+     does this automatically when thread context is present.
+
+5. Respond with the result.
+   - Explain the visual in one or two sentences only if needed.
+   - Do not claim the image proves anything. It is a visualization aid.
+
+## Prompt Contract
+
+For visual prompts, include:
+
+- `visual_type`
+- `main_subject`
+- `audience`
+- `flow_or_components`
+- `style_reference`
+- `brand_constraints`
+- `must_show`
+- `must_avoid`
+- `aspect_ratio`
+
+Use this shape internally:
+
+```text
+Create a [visual_type] showing [main_subject] for [audience].
+Composition: [layout and hierarchy].
+Content: [flow/components, 4-7 max].
+Style: [brand/design cues].
+Readable text: [short labels only].
+Avoid: [fake logos, claims, tiny text, generic stock visuals].
+Aspect ratio: [16:9 / 4:3 / square].
+```
+
+## Guardrails
+
+- Do not invent fake customer names, fake logos, fake metrics, fake compliance,
+  or market claims.
+- Do not create tiny unreadable UI text. Use simple labels and preserve detail
+  in the thread answer or source content.
+- Do not bake long paragraphs into images.
+- Do not use generic SaaS stock visuals when the user supplied a specific
+  domain, metaphor, or brand style.
+- If the user asks for a website asset or says "use it in the site", switch to
+  `landing-page-assets` because that needs asset role, alt text, and promotion.

package/assets/claude-local/skills/workspace-guidance-refresh/SKILL.md

@@ -23,6 +23,12 @@ does not match the current MinuteWork CLI export.
   - `mcp/claude-desktop.sample.json`
 - It does not regenerate tenant code, sidecar code, schema files, or arbitrary
   user-owned files outside the managed export set.
+- It never touches the authored overlays: `CLAUDE.workspace.md`,
+  `AGENTS.workspace.md`, and `skills.workspace/**`. These are deliberately
+  outside the managed manifest, so authored guidance and authored skills survive
+  every `sync-assets` (including `--force`) and are never reported as conflicts.
+  Keep workspace-specific guidance and skills in the overlays, not in the managed
+  `CLAUDE.md` / `AGENTS.md` / `skills/` files.
 - If the workspace uses an older exported skill set, prefer refreshing assets
   before concluding that a Builder capability or instruction is missing.
 - If the workspace lacks sandbox/tier guidance for `minutework sandbox create`,

package/assets/templates/vuilder-public-site/src/app/globals.css

@@ -53,6 +53,38 @@ a {
   max-width: 760px;
 }
 
+.hero-with-media {
+  grid-template-columns: minmax(0, 0.95fr) minmax(280px, 0.85fr);
+  max-width: none;
+  align-items: center;
+}
+
+.hero-copy {
+  display: grid;
+  gap: 24px;
+}
+
+.hero-media,
+.section-image,
+.feature-image {
+  overflow: hidden;
+  border: 1px solid var(--line);
+  background: var(--surface);
+}
+
+.hero-media {
+  aspect-ratio: 4 / 3;
+}
+
+.hero-media img,
+.section-image img,
+.feature-image img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
 .eyebrow {
   margin: 0;
   color: var(--accent);
@@ -96,8 +128,71 @@ p {
   padding: 24px;
 }
 
+.content-section,
+.cta-banner {
+  display: grid;
+  grid-template-columns: minmax(0, 0.9fr) minmax(240px, 0.7fr);
+  gap: 32px;
+  align-items: center;
+  margin-top: 56px;
+  padding-top: 56px;
+  border-top: 1px solid var(--line);
+}
+
+.content-section h2,
+.cta-banner h2 {
+  margin: 0;
+  font-size: clamp(2rem, 5vw, 4rem);
+  line-height: 1;
+}
+
+.section-image {
+  aspect-ratio: 4 / 3;
+}
+
+.feature-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(190px, 1fr));
+  gap: 16px;
+  margin-top: 28px;
+}
+
+.feature-item {
+  border: 1px solid var(--line);
+  background: var(--surface);
+  padding: 18px;
+}
+
+.feature-item h3 {
+  margin: 14px 0 0;
+  font-size: 1rem;
+}
+
+.feature-item p {
+  margin-bottom: 0;
+  font-size: 0.95rem;
+}
+
+.feature-image {
+  aspect-ratio: 16 / 10;
+}
+
 .site-footer {
   padding: 32px 0;
   border-top: 1px solid var(--line);
   color: var(--muted);
 }
+
+@media (max-width: 760px) {
+  .site-header {
+    align-items: flex-start;
+    gap: 16px;
+    flex-direction: column;
+  }
+
+  .hero-with-media,
+  .content-section,
+  .cta-banner {
+    grid-template-columns: 1fr;
+  }
+}

package/assets/templates/vuilder-public-site/src/app/page.tsx

@@ -1,15 +1,206 @@
 import Link from "next/link";
 
 import { appRoutes } from "@/lib/routes";
-import { getHomePageRef, getSiteManifest } from "@/lib/public-dj.server";
+import {
+  getHomePage,
+  getSiteManifest,
+  type PageSection,
+  type PublicSiteManifest,
+  type PublicSiteMediaAsset,
+} from "@/lib/public-dj.server";
+
+type UnknownRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): UnknownRecord | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function asRecordArray(value: unknown): UnknownRecord[] {
+  return Array.isArray(value)
+    ? value.map(asRecord).filter((item): item is UnknownRecord => item !== null)
+    : [];
+}
+
+function textValue(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function firstText(...values: unknown[]): string {
+  for (const value of values) {
+    const text = textValue(value);
+    if (text) {
+      return text;
+    }
+  }
+  return "";
+}
+
+function mediaByAssetKey(
+  manifest: PublicSiteManifest,
+  assetKey: string,
+): PublicSiteMediaAsset | null {
+  return (
+    manifest.payload.media.find(
+      (item: PublicSiteMediaAsset) => item.asset_key === assetKey,
+    ) ?? null
+  );
+}
+
+function mediaByRole(
+  manifest: PublicSiteManifest,
+  roles: string[],
+): PublicSiteMediaAsset | null {
+  return (
+    manifest.payload.media.find((item: PublicSiteMediaAsset) =>
+      roles.includes(item.role),
+    ) ?? null
+  );
+}
+
+function mediaFromImageField(
+  manifest: PublicSiteManifest,
+  value: unknown,
+): PublicSiteMediaAsset | null {
+  const image = asRecord(value);
+  if (!image) {
+    return null;
+  }
+  const assetKey = firstText(image.asset_key, image.assetKey);
+  if (assetKey) {
+    return mediaByAssetKey(manifest, assetKey);
+  }
+  const url = firstText(image.url, image.src);
+  if (!url) {
+    return null;
+  }
+  return {
+    asset_key: firstText(image.asset_key, image.assetKey, `inline-${url}`),
+    digest: firstText(image.digest, "inline"),
+    url,
+    alt_text: firstText(image.alt_text, image.altText, image.alt),
+    role: firstText(image.role, "section_illustration"),
+    metadata: {},
+  };
+}
+
+function renderImage(asset: PublicSiteMediaAsset, className: string) {
+  return (
+    <div className={className}>
+      <img src={asset.url} alt={asset.alt_text || ""} loading="lazy" />
+    </div>
+  );
+}
+
+function sectionImage(
+  manifest: PublicSiteManifest,
+  section: UnknownRecord,
+): PublicSiteMediaAsset | null {
+  return (
+    mediaFromImageField(manifest, section.image) ??
+    mediaFromImageField(manifest, section.visual) ??
+    null
+  );
+}
+
+function renderSection(
+  section: PageSection,
+  manifest: PublicSiteManifest,
+  index: number,
+) {
+  const record = asRecord(section) ?? {};
+  const type = firstText(record.type, "section");
+  const headline = firstText(record.headline, record.title);
+  const body = firstText(record.body, record.subhead, record.summary, record.markdown);
+  const image = sectionImage(manifest, record);
+
+  if (type === "feature_grid") {
+    const items = asRecordArray(record.items);
+    return (
+      <section className="content-section" key={`${type}-${index}`}>
+        {image ? renderImage(image, "section-image") : null}
+        <div>
+          {headline ? <h2>{headline}</h2> : null}
+          {body ? <p>{body}</p> : null}
+          {items.length ? (
+            <div className="feature-grid">
+              {items.map((item, itemIndex) => {
+                const itemImage = sectionImage(manifest, item);
+                return (
+                  <article className="feature-item" key={`${type}-${index}-${itemIndex}`}>
+                    {itemImage ? renderImage(itemImage, "feature-image") : null}
+                    <h3>{firstText(item.headline, item.title)}</h3>
+                    <p>{firstText(item.body, item.summary)}</p>
+                  </article>
+                );
+              })}
+            </div>
+          ) : null}
+        </div>
+      </section>
+    );
+  }
+
+  if (type === "cta_banner") {
+    const href = firstText(asRecord(record.cta)?.href) || appRoutes.onboarding();
+    const ctaLabel = firstText(asRecord(record.cta)?.label, "Start onboarding");
+    return (
+      <section className="cta-banner" key={`${type}-${index}`}>
+        <div>
+          {headline ? <h2>{headline}</h2> : null}
+          {body ? <p>{body}</p> : null}
+          <Link className="button" href={href}>
+            {ctaLabel}
+          </Link>
+        </div>
+        {image ? renderImage(image, "section-image") : null}
+      </section>
+    );
+  }
+
+  if (type === "content_markdown" || headline || body || image) {
+    return (
+      <section className="content-section" key={`${type}-${index}`}>
+        <div>
+          {headline ? <h2>{headline}</h2> : null}
+          {body ? <p>{body}</p> : null}
+        </div>
+        {image ? renderImage(image, "section-image") : null}
+      </section>
+    );
+  }
+
+  return null;
+}
 
 export default async function HomePage() {
-  const [manifest, homePage] = await Promise.all([getSiteManifest(), getHomePageRef()]);
-  const headline = String(manifest.payload.metadata.headline ?? manifest.display_name);
-  const summary = String(
-    manifest.payload.metadata.summary ??
+  const [manifest, homePage] = await Promise.all([getSiteManifest(), getHomePage()]);
+  const sections: PageSection[] = homePage?.payload.sections ?? [];
+  const heroSection =
+    sections.find((section: PageSection) => firstText(section.type) === "hero_with_cta") ??
+    null;
+  const heroRecord = asRecord(heroSection) ?? {};
+  const heroAsset =
+    sectionImage(manifest, heroRecord) ??
+    mediaByRole(manifest, ["hero_background", "hero_visual"]);
+  const headline =
+    firstText(
+      heroRecord.headline,
+      manifest.payload.metadata.headline,
+      homePage?.title,
+      manifest.display_name,
+    ) || manifest.display_name;
+  const summary =
+    firstText(
+      heroRecord.subhead,
+      heroRecord.summary,
+      manifest.payload.metadata.summary,
       "A custom Vuilder public site rendered from pinned public-dj content.",
-  );
+    ) || "A custom Vuilder public site rendered from pinned public-dj content.";
+  const cta = asRecord(heroRecord.cta);
+  const ctaLabel = firstText(cta?.label, "Start onboarding");
+  const ctaHref = firstText(cta?.href) || appRoutes.onboarding();
 
   return (
     <div className="site-shell">
@@ -22,14 +213,24 @@ export default async function HomePage() {
         </nav>
       </header>
       <main className="site-main">
-        <section className="hero">
-          <p className="eyebrow">{manifest.vertical_slug}</p>
-          <h1>{headline}</h1>
-          <p>{summary}</p>
-          <Link className="button" href={appRoutes.onboarding()}>
-            Start onboarding
-          </Link>
+        <section className={heroAsset ? "hero hero-with-media" : "hero"}>
+          <div className="hero-copy">
+            <p className="eyebrow">{manifest.vertical_slug}</p>
+            <h1>{headline}</h1>
+            <p>{summary}</p>
+            <Link className="button" href={ctaHref}>
+              {ctaLabel}
+            </Link>
+          </div>
+          {heroAsset ? renderImage(heroAsset, "hero-media") : null}
         </section>
+        {sections
+          .filter(
+            (section: PageSection) => firstText(section.type) !== "hero_with_cta",
+          )
+          .map((section: PageSection, index: number) =>
+            renderSection(section, manifest, index),
+          )}
         <section className="panel">
           <p>
             Release manifest: {manifest.content_ref} / {manifest.digest}