How the three skills work, how they hand off to each other, and every background system that stores, publishes or serves your creatives. Colour-coded so you can follow one system across every diagram.
0.The whole thing in one breath
You describe a creative in plain English in Claude Code. Claude follows the kie-ai skill to pick the best AI model on the KIE.ai marketplace and make it. The creative-store skill then saves the finished file to your own Cloudflare R2 storage and logs what it cost in your Supabase database. You view it any time on your platform (a Cloudflare Pages website). The kie-ad-studio skill sits on top and does all of that for a properly on-brand ad. Your KIE key is pasted once into the platform, encrypted, and fetched only when a skill needs it. The platform itself updates automatically whenever code is pushed to your private GitHub repo.
1.The cast: eight moving parts
Each has one job. The colour next to each name is used in every diagram below.
Your machine
Claude Code (the IDE)
The command line where you type requests. Runs the skills and holds a small .env file.
The actual .jpg/.mp4 is saved to your R2 bucket, filed by brand/project.
+
Supabase
Log the record
A row for the creative and a row for the credits spent.
→
You (browser)
View in Gallery
Log in to the platform. The Gallery reads the list and shows each image from R2, with total spend.
Key point: the heavy file lives in R2, the facts about it (model, prompt, cost, brand) live in Supabase, and the platform stitches them together for your eyes.
3.Your KIE key: pasted once, never in a file
This is the security bit you asked for. The key never sits on your computer or in the code.
You (browser)
Paste in Settings
Once, on the platform's Settings page.
→
Platform Function
Encrypt
Scrambles it (AES-GCM) with a secret only Cloudflare holds.
→
Supabase
Store scrambled
Only the encrypted version is saved. The browser can never read it back.
↺
A skill needs it
Request the key
The skill asks the platform, proving itself with one token from .env.
→
Platform Function
Decrypt + return
Unscrambles it and hands it back, just for that one job.
Your machine only ever holds two harmless values in .env: the platform address and one access token. The real KIE key is encrypted in the cloud and can be changed from the Settings page without touching anything on your PC.
4.How the platform updates itself
You never "publish" by hand. Pushing code is the publish button.
Claude Code
Change the code
A tweak to a page or a Function.
→
GitHub
Push to main
Saved to the private AIOS repo.
→
Cloudflare Pages
Auto-build
Notices the push, rebuilds the site (~1 minute).
→
You (browser)
Live
The new version is online at the same address.
Note: platform secrets (like the KIE encryption key) only take effect on a fresh deploy, so changing one is followed by a redeploy.
5.Each skill on its own
kie-ai The generator
Turns a request into a finished KIE generation, and teaches itself each model as it goes.
Understand the request (type, size, brand).
Pick a model from a curated shortlist, or research a new one.
Reuse or build a small script for that exact model. It saves each one so next time is instant.
Run it (fetch key → submit → wait → get URLs).
Self-heal: if a model breaks, it marks that script "stale" and repairs it next time.
creative-store The archivist
Takes a generated result and makes it permanent and viewable.
Receives the result URL + details from kie-ai.
Sends them to the platform (proving itself with the access token).
The platform downloads the file before its link expires.
Stores the file in R2 and writes the creative + spend rows in Supabase.
Returns the Gallery link.
kie-ad-studio The creative director
The full ad workflow. Drives the other two, adds brand discipline.
Confirms brand + project.
Loads the brand kit (colours, fonts, tone, rules).
Writes the prompt to brief and brand.
Generates via kie-ai, then QAs the result (checks text, colours, wording).
Stores via creative-store and shows you the Gallery.
How they relate
Think of it as a chain of command:
kie-ad-studio
decides what and on-brand
→
kie-ai
makes it
→
creative-store
keeps it
You can also call kie-ai alone (just make something), or kie-ai + creative-store (make and keep) without the ad layer.
6.Real scenarios, start to finish
Scenario A · "Just make me an image" (no saving)
You Ask in Claude Code. e.g. "make me a hero image of a water cooler"
kie-ai Picks a model, fetches the key, generates. Uses KIE.ai, spends a few credits.
kie-ai Returns the image link(s) to you in the chat. Nothing stored yet. Links expire in ~20 minutes.
Scenario B · "Make it and keep it"
You Ask, and say to save it to a brand/project.
kie-ai Generates via KIE.ai.
creative-store Hands the result to the platform.
Platform Downloads it, saves the file to R2, writes the record + spend to Supabase.
You Open the platform Gallery and see it, with the cost logged.
Scenario C · "Make a proper on-brand ad"
You "Make a 1:1 Technolease CCTV ad, headline RENT DON'T BUY."
kie-ad-studio Loads the Technolease brand kit, writes a branded prompt, checks credits with you.
kie-ai Generates via KIE.ai.
kie-ad-studio QAs it (colours right, text legible, "rental" not "lease"). Re-rolls or edits if needed.
creative-store → Platform → R2 + Supabase.
You View the finished ad in the Gallery.
Scenario D · A model misbehaves (the self-heal)
This actually happened on day one, and it's by design.
kie-ai Tries imagen4-fast. KIE.ai returns an internal error (their side).
kie-ai Marks that model "stale" in its registry with the error, and spends no credits on the failure.
kie-ai Switches to a working model (grok-imagine) and succeeds.
Next time imagen4-fast is asked for, the skill knows it was flaky and re-checks or repairs it first.
Scenario E · Changing the platform itself
You/Claude Edit a page or a Function.
GitHub The change is pushed to main.
Cloudflare Pages Rebuilds automatically in about a minute.
You Refresh the site, the update is live. No manual publish.
7.Where everything lives and how it's reached
Thing
Where it's stored
How it's accessed
The creative files (jpg, mp4)
R2 bucket aios-creatives
Served to the Gallery through a platform Function by its unique key
Creative records + spend
Supabase tables creatives, kie_spend
Read by the Gallery when you're logged in
Your KIE key (encrypted)
Supabase table app_settings
Only via the platform's secure fetch, decrypted per job
Your login
Supabase Auth
Email + password on the platform
The platform code
GitHub repo SeanMac19/AIOS
Auto-deployed to Cloudflare Pages on push
The skills + per-model scripts
Your workspace .claude/skills/
Run by Claude Code on your PC
Platform address + access token
Your .env (on your PC, never shared)
Used by the skills to reach the platform
The generated result (temporary)
KIE.ai temp storage (~20 min)
Fetched immediately, then it's in R2 for good
8.Good-to-knows
Why two Cloudflare things? The Pages platform is your website. The separate Worker (aios-data-sync) runs the daily marketing data pull, which needs a timed trigger Pages can't do. Both read the same Supabase.
Credits. Generating spends KIE credits; failures don't. Every successful generation logs its cost to Supabase, so the Gallery can show total spend.
Why the 20-minute thing? KIE only keeps a fresh result link for ~20 minutes. That's why creative-store grabs it straight after generating, so your copy in R2 is permanent.
Do I need to "publish" creatives? No. Saving via creative-store puts it in the Gallery instantly. "Publishing" only ever refers to the platform code auto-deploying from GitHub.
What needs the internet? Generating (KIE), storing (R2), the Gallery and Settings (the platform). The skills themselves live on your PC. This explainer works offline.
Where's the risk kept low? The KIE key is encrypted and never on your PC. R2 files use unguessable names. The database is locked so only a logged-in you (or the secure Functions) can read it.