vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/add-ai/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: add-ai
+description: the builder wants smart replies or another AI feature in their app. Use when the builder says something like: add ai; chatbot; smart replies.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-ai
+
+**Goal:** the builder wants smart replies or another AI feature in their app.
+
+**Contract:** one action at a time · verify-before-advance · plain language · translate errors · celebrate.
+
+> (Under the hood — agent-only) Wire `@vybekiit/ai` → `resolveAiProvider()` via `src/lib/ai-client.ts`.
+> Never name OpenAI/Anthropic to the builder — say "smart replies" or "AI helper".
+>
+> ⚠️ This skill covers one-shot AI (single `complete()` call). If the builder asks for a **chatbot
+> or agent loop** (multi-turn with tool-calling), that requires anti-hallucination guards: track
+> whether tools were actually called, force a real tool call before accepting any data claim, and
+> never let the model describe tool usage without actually invoking the tool. This is out of scope
+> for v1 — surface it as a feature request and note the pattern in checklist.md.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/AiAssistantPage.tsx` export `AiAssistantPage` into the buyer app at route `/dashboard/ai`.
+   Recipe id: `ai-assistant`. Presets: ai_conversations + embeddings.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-ai')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Explain in one line.** *"I'll add a smart helper that answers using AI."*
+2. **Collect the API key** into secret settings if not already present (`OPENAI_API_KEY` default).
+   Run `vybekiit apply-preset embeddings` and `vybekiit apply-preset ai_conversations` when chat history
+   is needed (`platform-skills/db-presets-vybekiit.md`).
+   **Verify:** keys saved; `vybekiit verify-presets embeddings` when presets applied.
+3. **Wire one feature** the builder asked for using `getAi().complete()` on the server only.
+   **Verify:** build succeeds; test path returns text.
+4. **Celebrate** when a real response works in the app.
+
+## Definition of done
+
+One AI-powered flow works end-to-end with a passing test on the server path.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-analytics/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: add-analytics
+description: the builder can see who uses their app — visitor stats in plain language. Use when the builder says something like: visitor stats; analytics; track usage.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-analytics
+
+**Goal:** the builder can see who uses their app — visitor stats in plain language.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You wire analytics; the builder never sees provider dashboards
+unless you screen-share a summary.
+
+> (Under the hood — agent-only) Wire Plausible or PostHog via `resolveAnalyticsProvider()` from
+> `@vybekiit/analytics` (see `src/lib/analytics-client.ts` and `VybeAnalytics`). Never name the
+> provider to the builder — say "visitor stats". Replace dashboard analytics placeholder
+> (`TODO(vybekiit): … — skill: add-analytics`).
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/AnalyticsPage.tsx` export `AnalyticsPage` into the buyer app at route `/dashboard/analytics`.
+   Recipe id: `analytics`. Presets: none.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-analytics')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Explain in one line.** *"I'll set up visitor stats so you can see how many people use your app."*
+
+2. **Pick a provider and collect one value.** Choose Plausible (simple) or PostHog (richer) based on
+   needs — default Plausible for v1. Ask the builder to create an account if needed; collect the site
+   id / project key **one at a time** into the secret settings file.
+   **Verify:** key saved.
+
+3. **Wire the snippet.** Add the tracking script to the app layout (web) or equivalent entry point.
+   For mobile/extension, wire through the backend or a minimal client event if applicable.
+   **Verify:** build succeeds; no console errors on load.
+
+4. **Confirm data flows.** Open the app once yourself; check the provider dashboard shows at least one
+   visit (or use their test/debug mode).
+   **Verify:** at least one event recorded. 🎉 *Celebrate* — they can see visitor stats.
+
+5. **Optional dashboard link.** Add a plain "View stats" link in the builder dashboard that opens the
+   provider UI — only if they asked for easy access.
+
+## If anything breaks
+
+Run `doctor`. Common cause: wrong site id or ad blockers in dev — test in a normal browser window.
+If MCP fails once, run `vybekiit doc-fallback posthog` or `vybekiit doc-fallback plausible`.
+
+## Definition of done
+
+Visitor stats record at least one page view, and the builder knows where to check numbers in plain words.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-app-clip/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: add-app-clip
+description: Add an iOS App Clip target to an Expo app. Use when the user mentions App Clip, AASA, apple-app-site-association, appclips, smart app banner, or wants to ship a lightweight iOS Clip invoked from a URL alongside their parent app.
+---
+
+# Add an App Clip to an Expo App
+
+Adds an iOS App Clip target to an Expo project. The Clip lives in `targets/clip/`, ships alongside the parent app, and is invoked from a URL on the app's domain via an Apple App Site Association (AASA) file.
+
+The parent app's bundle ID becomes `com.<username>.<app-name>` and the Clip's is automatically derived as `<parent>.clip` (e.g. `com.bacon.may20.clip`).
+
+## 1. Set `bundleIdentifier` and `appleTeamId`
+
+`bun create target` warns if these are missing. Add to `app.json`:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "bundleIdentifier": "com.<username>.<app-name>",
+      "appleTeamId": "XX57RJ5UTD"
+    }
+  }
+}
+```
+
+## 2. Add the App Clip target
+
+```sh
+bun create target clip
+```
+
+This installs [`@bacons/apple-targets`](https://github.com/EvanBacon/expo-apple-targets), adds it to the `plugins` array in `app.json`, and writes:
+
+- `targets/clip/expo-target.config.js` — the target's config plugin
+- `targets/clip/Info.plist` — Clip Info.plist
+- `targets/clip/AppDelegate.swift`, `Assets.xcassets`, etc.
+
+Pick a good icon or reuse the existing one defined in the app — check it with `bunx expo config` under the `icon` or `ios.icon` key.
+
+## 3. Wire up associated domains
+
+The parent app and the Clip each need the Associated Domains entitlement pointing at the domain that hosts the AASA file.
+
+In `app.json`, add both `applinks:` (parent) and `appclips:` (Clip invocation) entries:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "associatedDomains": [
+        "applinks:may20.expo.app",
+        "appclips:may20.expo.app"
+      ]
+    }
+  }
+}
+```
+
+In `targets/clip/expo-target.config.js`, declare the Clip's entitlement:
+
+```js
+/** @type {import('@bacons/apple-targets/app.plugin').ConfigFunction} */
+module.exports = (config) => ({
+  type: "clip",
+  icon: "https://github.com/expo.png",
+  entitlements: {
+    "com.apple.developer.associated-domains": ["appclips:may20.expo.app"],
+  },
+});
+```
+
+> If you skip this, `expo prebuild` will print: `Apple App Clip may require the associated domains entitlement but none were found`.
+
+## 4. Register bundle IDs and create the App Store entry
+
+```sh
+bunx setup-safari
+```
+
+This logs in to the Apple Developer account, registers `com.bacon.may20`, creates the App Store Connect entry, and prints:
+
+- A starter `apple-app-site-association` JSON
+- A `<meta name="apple-itunes-app">` tag with the iTunes app id
+- Team ID, iTunes ID, and Bundle ID
+
+## 5. Host the AASA file
+
+App Clips are invoked when iOS fetches `https://<your-domain>/.well-known/apple-app-site-association` and finds a matching `appclips` entry.
+
+```sh
+mkdir -p public/.well-known
+touch public/.well-known/apple-app-site-association
+```
+
+Paste the JSON `setup-safari` printed, but **add an `appclips` block** for the Clip's full app ID (`<TeamID>.<ClipBundleID>`). The output of `setup-safari` only covers the parent app:
+
+```json
+{
+  "applinks": {
+    "details": [
+      {
+        "appIDs": ["XX57RJ5UTD.com.bacon.may20"],
+        "components": [{ "/": "*", "comment": "Matches all routes" }]
+      }
+    ]
+  },
+  "appclips": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20.clip"]
+  },
+  "activitycontinuation": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20"]
+  },
+  "webcredentials": {
+    "apps": ["XX57RJ5UTD.com.bacon.may20"]
+  }
+}
+```
+
+Notes:
+
+- The file has **no extension** and **no `Content-Type` requirements** beyond being served as-is. Expo Router static export serves files in `public/` verbatim.
+- The `appclips` block is what lets a URL on the domain launch the Clip.
+- `webcredentials` is used for sharing credentials between the website, parent app, and the App Clip.
+- `activitycontinuation` is optional and used for sharing the link between mobile and desktop. Must be used with `Head` from expo-router — see https://docs.expo.dev/router/advanced/apple-handoff/
+- Notation and route-disabling details: https://sosumi.ai/documentation/xcode/supporting-associated-domains
+
+## 6. Add the Smart App Banner meta tag
+
+Create `src/app/+html.tsx` (Expo Router's HTML shell) and add the tag from `setup-safari`. Create the versioned template if it doesn't exist:
+
+```sh
+bunx expo customize src/app/+html.tsx
+```
+
+Add the meta tag to the `<head>`:
+
+```tsx
+import { ScrollViewStyleReset } from "expo-router/html";
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="apple-itunes-app" content="app-id=6771566491" />
+        <ScrollViewStyleReset />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+To make the website show the App Clip card instead of the install card, use:
+
+```html
+<meta
+  name="apple-itunes-app"
+  content="app-id=6771566491, app-clip-bundle-id=com.bacon.may20.clip, app-clip-display=card"
+/>
+```
+
+## 7. Deploy the website
+
+The AASA file must be live before iOS will trust the association. Use [EAS Hosting](https://docs.expo.dev/eas/hosting/):
+
+```sh
+bunx expo export -p web
+eas deploy --prod
+```
+
+This publishes the site (including `/.well-known/apple-app-site-association`) at `https://<slug>.expo.app`. Verify:
+
+```sh
+curl https://may20.expo.app/.well-known/apple-app-site-association
+```
+
+## 8. Mirror permissions
+
+Inspect the parent app's permissions after prebuild:
+
+```sh
+npx expo config --type introspect
+```
+
+Look at the `infoPlist` object — mirror the permission keys in the App Clip's `Info.plist` so matching APIs can be used from the Clip.
+
+Set `deploymentTarget: "17.6"` in the Clip's target config — App Clips have a higher minimum size limit in iOS 17.6.
+
+If the app uses push notifications or location services, add to the App Clip's `Info.plist` to request the necessary permissions:
+
+```xml
+<key>NSAppClip</key>
+<dict>
+  <key>NSAppClipRequestEphemeralUserNotification</key>
+  <false/>
+  <key>NSAppClipRequestLocationConfirmation</key>
+  <true/>
+</dict>
+```
+
+## 9. Build and submit to TestFlight
+
+```sh
+bunx testflight
+```
+
+This will:
+
+1. Generate an `eas.json` if missing.
+2. Set up credentials for **both** targets (parent + Clip). Each gets its own provisioning profile but can share a single Distribution Certificate.
+3. Sync capabilities — note `Enabled: Associated Domains` for the Clip target.
+4. Build, upload, and schedule a TestFlight submission.
+
+## 10. Configure App Clip metadata
+
+Pull existing App Store metadata to local:
+
+```sh
+eas metadata:pull
+```
+
+Add `apple.appClip` to `store.config.json`. Up to 3 invocation URLs can launch the Clip from a web page:
+
+```json
+{
+  "configVersion": 0,
+  "apple": {
+    "appClip": {
+      "defaultExperience": {
+        "action": "PLAY",
+        "releaseWithAppStoreVersion": true,
+        "reviewDetail": {
+          "invocationUrls": ["https://may20.expo.app/", null, null]
+        },
+        "info": {
+          "en-US": {
+            "subtitle": "Instantly native with Expo",
+            "headerImage": "store/apple/app-clip/en-US/asc-app-clip.png"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `headerImage` must be a 1800x1200 PNG with no opacity.
+
+Push back to the store:
+
+```sh
+eas metadata:push
+```
+
+Apple's recommended App Clip metadata guidelines: https://sosumi.ai/documentation/appclip/configuring-the-launch-experience-of-your-app-clip
+
+## What you get
+
+- Parent app target: `com.bacon.may20`
+- App Clip target: `com.bacon.may20.clip`, lives in `targets/clip/`
+- AASA hosted at `https://may20.expo.app/.well-known/apple-app-site-association`
+- Smart App Banner meta tag on every web route
+- Every route linked to its native counterpart
+- TestFlight build of the parent app with the Clip embedded
+
+Once Apple invokes the Clip from a URL on the domain, iOS opens `targets/clip/`'s entry point which loads the React Native app.
+
+## Native detection (optional)
+
+To let JS detect when it's running inside an App Clip and present an install prompt for the full app, create a local Expo module (`bunx create-expo-module --local`) that exposes `navigator.appClip.prompt()`.
+
+See [./references/native-module.md](./references/native-module.md) for the Swift module, TypeScript interface, and usage.
+
+## References
+
+- ./references/native-module.md — Local Expo module to detect App Clip context and present the SKOverlay install prompt

package/dist/global-skills/add-app-clip/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Add App Clip"
+  short_description: "Add an iOS App Clip target to an Expo app with AASA, associated domains, and TestFlight setup"
+  default_prompt: "Use $add-app-clip when adding or reviewing an iOS App Clip target for an Expo app, including bundle IDs, associated domains, AASA files, smart app banners, App Store Connect setup, and TestFlight verification."

package/dist/global-skills/add-app-clip/references/native-module.md

@@ -0,0 +1,96 @@
+# Native App Clip detection
+
+Create a local Expo module so JS can detect when the app is running inside an App Clip and present the install prompt for the full app.
+
+```sh
+bunx create-expo-module --local
+```
+
+## Swift module
+
+```swift
+import ExpoModulesCore
+import StoreKit
+
+internal class MissingCurrentWindowSceneException: Exception {
+  override var reason: String {
+    "Cannot determine the current window scene in which to present the modal for requesting a review."
+  }
+}
+
+internal class MissingContainerURLException: Exception {
+  override var reason: String {
+    "Cannot determine the container URL."
+  }
+}
+
+public class AppClipModule: Module {
+  private static let isAppClip: Bool = {
+    if let infoPlist = Bundle.main.infoDictionary, let _ = infoPlist["NSAppClip"] as? [String: Any] {
+      return true
+    }
+    return false
+  }()
+
+  public func definition() -> ModuleDefinition {
+    Name("AppClip")
+
+    Constant("isAppClip") {
+      AppClipModule.isAppClip
+    }
+
+    // Display overlay to advertise full app.
+    // https://developer.apple.com/documentation/app_clips/recommending_your_app_to_app_clip_users
+    AsyncFunction("prompt") {
+      if #available(iOS 16, *) {
+        guard let currentScene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
+          throw MissingCurrentWindowSceneException()
+        }
+
+        let config = SKOverlay.AppClipConfiguration(position: .bottom)
+        let overlay = SKOverlay(configuration: config)
+        overlay.present(in: currentScene)
+      }
+    }.runOnQueue(DispatchQueue.main)
+  }
+}
+```
+
+## TypeScript interface
+
+```ts
+import { NativeModule, requireOptionalNativeModule } from "expo";
+
+declare class AppClipModule extends NativeModule<{}> {
+  prompt(): void;
+  isAppClip?: boolean;
+}
+
+const AppClipNative = requireOptionalNativeModule<AppClipModule>("AppClip");
+
+if (AppClipNative?.isAppClip) {
+  navigator.appClip = {
+    prompt: AppClipNative.prompt,
+  };
+}
+
+declare global {
+  interface Navigator {
+    /**
+     * Only available in an App Clip context.
+     * @expo
+     */
+    appClip?: {
+      /** Open the SKOverlay */
+      prompt: () => void;
+    };
+  }
+}
+
+export {};
+```
+
+## Usage
+
+- Detect App Clip context: `if (navigator.appClip) { ... }`
+- Prompt to install the full app: `navigator.appClip?.prompt()`

package/dist/global-skills/add-blog/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: add-blog
+description: the builder wants a blog or changelog on their site. Use when the builder says something like: add a blog; write articles; changelog.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-blog
+
+**Goal:** the builder wants a blog or changelog on their site.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+> (Under the hood — agent-only) `@vybekiit/cms` + `@vybekiit/seo` via `cms-client.ts` and `seo.ts`.
+> Content lives in `content/*.mdx`; routes under `app/[locale]/blog/`; sitemap via `app/sitemap.ts`;
+> GEO via `app/llms.txt/route.ts`, `VybeJsonLd`, and `buildBlogGeo()`.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/BlogPage.tsx` export `BlogPage` into the buyer app at route `/blog`.
+   Recipe id: `blog`. Presets: none.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-blog')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. Explain: *"I'll add blog pages you can edit as simple files."*
+2. Add MDX pages under `content/` (title from `#` heading; optional description in front matter).
+3. Blog index at `/blog` lists pages via `getCms().listPages()`; each post at `/blog/[slug]`.
+4. Wire page metadata with `buildPageMetadata()` or `buildBlogGeo(slug)` → Next `Metadata` + Open Graph.
+5. Add `<VybeJsonLd data={...} />` on each post — `buildJsonLdBlogPosting()` for articles; `buildJsonLdFaq()` when the post has an answer-first FAQ block.
+6. After adding pages, confirm `/llms.txt` lists new `/blog/*` URLs (`buildLlmsTxt()` in `app/llms.txt/route.ts`).
+7. Hub-spoke internal links: link from `/blog` to each post with descriptive anchors (`suggestInternalLinks()` — keyword anchors, never "click here").
+8. **Verify:** blog index and post render; view-source shows JSON-LD; `/llms.txt` returns 200 with new paths; sitemap includes `/blog` and post slugs.
+
+## Definition of done
+
+At least one blog page is live, listed in the sitemap, cited in `/llms.txt`, and carries JSON-LD on the post page.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-crud/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: add-crud
+description: scaffold create/read/update/delete routes for a resource. Use when the builder says something like: crud; create read update delete.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-crud
+
+**Goal:** scaffold create/read/update/delete routes for a resource.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Agree on the resource name in plain words (e.g. "posts", "orders").
+2. Run `vybekiit backend add-crud <resource>`.
+3. Swap in-memory store for `@vybekiit/db` when ready.
+4. **Verify:** list, create, read, update, delete all work.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-files/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: add-files
+description: users can upload files and images, and see them back in the app. Use when the builder says something like: upload; store files; attachments.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-files
+
+**Goal:** users can upload files and images, and see them back in the app.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You build the upload; the builder only pastes a value when asked.
+
+> (Under the hood — agent-only) Use `@vybekiit/db`'s `resolveStorageProvider()` for upload + read.
+> After upload, display URLs from `resolveAssetDelivery().url()` — not raw `getUrl()` — so images
+> are compressed and served via the kit's CDN layer. The default is Supabase Storage / R2 once
+> doctor provisions Cloudflare; `s3` is opt-in via `STORAGE_PROVIDER`. Same skill, whichever
+> is set — never name the service to the builder.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/FileManagerPage.tsx` export `FileManagerPage` into the buyer app at route `/dashboard/files`.
+   Recipe id: `file-manager`. Presets: file_metadata.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-files')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Make sure file storage is ready.** Run `vybekiit doctor` so the storage tool is set up, and
+   collect any access key it needs — one at a time — into the secret settings file.
+   **Verify:** storage is reachable (a tiny test upload succeeds).
+
+2. **Add the upload UI + handler.** Build a simple "choose a file" control and a handler that sends
+   the file through `resolveStorageProvider()`.
+   **Verify:** the screen builds and shows the upload control.
+
+3. **Show the uploaded file back.** After upload, display the image/file via
+   `resolveAssetDelivery().url()` (use `VybeImage` for images) so the CDN serves an optimized variant.
+   **Verify:** an uploaded file appears in the app.
+
+4. **Write a test** for the upload handler, and keep it green.
+
+5. **Try it for real.** Upload a real image and confirm it shows up.
+   **Verify:** the file uploads and displays.
+   🎉 *Celebrate* — users can share files now.
+
+## If anything breaks
+
+Run `doctor`. Most issues are a missing access key or storage not set up yet — fix it for them,
+don't explain the internals.
+
+## Definition of done
+
+A real file uploads and displays, and a passing test covers the upload handler.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*