--- name: oeave-project description: 'Build or edit an Oeave project through the Agent HTTP API. Creates fibers, threads, components, style, uploads assets, triggers depth maps / embeddings, and publishes. Use when the user asks you to "build", "flesh out", "fill in", "populate", "publish" or "edit" an Oeave project.' --- # Oeave Project Builder You're building content for an Oeave project using the Agent HTTP API. This document tells you the workflow patterns that work reliably. The base URL and endpoint catalog are authoritative — when in doubt, call `/docs` and follow what it says. --- ## 0. Credentials Before any API call, make sure you have the user's API key in the environment: ``` OEAVE_API_KEY=oea_live__ ``` **If you don't have a key, stop and direct the user to generate one.** Tell them, in plain terms: > "I need an Oeave API key to build in your project. Go to [https://www.oeave.com/settings/](https://www.oeave.com/settings/) and scroll to the **API keys** section. Click **New API key**, name it (e.g. _Claude Code_), leave the scopes on **Full (no delete)** unless you want to restrict me, and click **Create key**. The secret is shown once — copy it and paste it back here (or set it as `OEAVE_API_KEY` in your env)." Never embed the key in code files or commit it to git — use it as an env var only. If the key leaks, the user should revoke it from the same settings page. The API base URL is hardcoded: ``` https://api.oeave.com/agent/v1 ``` All paths below are relative to that. --- ## 1. ALWAYS fetch `/docs` first The fiber kinds, component kinds, scopes, endpoints, quotas, and error codes can evolve. Start every session with: ```bash curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ https://api.oeave.com/agent/v1/docs | jq ``` Read `conventions`, `endpoints`, `fiberKinds`, `componentKinds`, and `style`. Treat it as the source of truth — if anything in this document contradicts `/docs`, follow `/docs`. Then call `/me` to confirm the key works, see your tier, scopes, current monthly usage, and limits: ```bash curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ https://api.oeave.com/agent/v1/me | jq ``` - `401` → the key is invalid/revoked/expired. - `403 insufficient_scope` on a later call → ask the user to regenerate a key with the missing scope (the error includes `error.details.requiredScope`). --- ## 2. Pick the project One key can see multiple projects. List them: ```bash curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ https://api.oeave.com/agent/v1/projects | jq ``` Ask the user which one to work on, or accept a slug/name in the invocation. Every subsequent path needs the project id as `:pid`. --- ## 3. Understand what's already there Before creating anything, survey: ```bash PID= # Existing fibers (content atoms) curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ "https://api.oeave.com/agent/v1/projects/$PID/fibers" \ | jq '.data.items[] | {id, kind, title: .data.title, order}' # Existing threads curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ "https://api.oeave.com/agent/v1/projects/$PID/threads" \ | jq '.data.items[] | {id, title, funnelStage}' # Existing assets curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ "https://api.oeave.com/agent/v1/projects/$PID/assets" \ | jq '.data.items[] | {id, kind, fileName}' # Style curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ "https://api.oeave.com/agent/v1/projects/$PID/style" \ | jq '.data.desktop | {presentationMode, colors, headingFont: .headingFont.family}' ``` **Do not duplicate.** If a fiber on the same topic exists, prefer PATCH over POST. Before creating a fiber on a non-trivial topic, run a vector search against what's already stored: ```bash curl -s -G -H "Authorization: Bearer $OEAVE_API_KEY" \ --data-urlencode "q=battery life" \ "https://api.oeave.com/agent/v1/projects/$PID/search/fibers" | jq '.data.items[] | {id, kind, score, title: .data.title}' ``` Items with a high score (> ~0.75) likely cover the topic — PATCH them instead of creating a sibling. --- ## 3b. Ask where to source content from Before asking the user *what* to build, ask *where you should pull from*. Fibers and threads need real source material — without it you'll either fabricate or nag the user for every field. Prompt the user for one or more of: - **A website URL** — marketing site, docs, landing page. You can scrape copy directly, and use `POST /projects/:pid/style/import-from-url` to pull colors/fonts/logo. - **A code repo or local path** — README, docs folder, marketing pages in the repo. Read files via your own filesystem tools and mine them for features, setup steps, specs. - **Uploaded files** — PDFs, decks, spec sheets, images, 3D models, videos the user can point you to on disk. - **Pasted notes** — raw text the user drops into the chat (positioning, audience, taglines). - **Existing fibers/threads** — if the survey in §3 already shows meaningful content, you may not need new sources; offer to augment what's there. Once you know the sources, propose a direction (survey-first, specific gap, full funnel, style import, act on suggestions, publish) grounded in what's actually available. If the user picks a direction without naming a source, ask for one before creating fibers. --- ## 4. Mental model - **Project** has one **Product** (typically 1:1). The product holds a `threads[]` array. - **Fibers** are independent content atoms (image, featureCard, testimonial, …). They're stored per-project and referenced by threads. - **Threads** are ordered sequences of **Components**. Some components reference fibers via `fiberIds`; others carry inline content. - **Style** is a `{ desktop, mobile }` theme. - **Embeddings** power vector search and are rebuilt automatically whenever a fiber/thread is written. The fiber's content is fingerprinted on each successful embed; identical content + question config short-circuits subsequent reembeds. --- ## 4b. Coverage principles **Always populate a `productProfile` fiber.** It's the anchor for the whole project — name, tagline, category, audience, key attributes. If one doesn't exist, create it early from the content sources (§3b). If it exists but is thin, augment it via PATCH before building other fibers. Never leave it empty. **Be comprehensive — more fibers, better experience.** The renderer, search, suggestions, and embeddings all improve as fiber coverage grows. Don't stop at the minimum viable set. After the obvious fibers (productProfile, brandStory, a few featureCards), keep going: testimonials, faqs, howItWorks, pricing, pressMention, caseStudy, comparison, useCase, problemStatement, guarantee, targetAudience, coreValues, designPhilosophy, behindTheScenes, timeline — anything the sources support. Prefer adding one more well-sourced fiber over stopping early. **Find and upload strong brand imagery.** Visuals carry the experience. Hunt through the provided sources for: - **Hero/lifestyle shots, product photos, mood imagery** — upload as assets and reference from `image`, `featureCard`, `testimonial`, `caseStudy`, `productProfile`, `brandStory` fibers. Use `variants: ["depth"]` on hero/mood shots so the 3D depth effect works. - **Logos and brand graphics** — populate `style.desktop.brandGraphic` (and `mobile.brandGraphic`) with the brand's logo/wordmark. Prefer transparent PNG or SVG; upload as an asset and reference `{ assetId }`. - **If the source is a website**, scrape its `` tags, OG images, and favicons; if it's a repo, check `public/`, `assets/`, `static/`, and README images. If nothing usable exists, tell the user and ask them to point you at image files or a press kit rather than shipping a text-only project. --- ## 5. Workflow patterns ### 5a. Uploading a media asset Any `{ assetId }` shorthand in a fiber/component/style body requires an asset row. To create one: ```bash # 1) Compute sha256 of the file SHA=$(shasum -a 256 bottle.jpg | awk '{print $1}') # 2) Request an upload URL RESP=$(curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ -H "Content-Type: application/json" \ -X POST "https://api.oeave.com/agent/v1/projects/$PID/assets/uploads" \ -d "{\"fileName\":\"bottle.jpg\",\"contentType\":\"image/jpeg\",\"sha256\":\"$SHA\"}") # If reused==true, grab the existing assetId and skip the upload. # Otherwise: UPLOAD_URL=$(echo "$RESP" | jq -r .data.uploadUrl) R2_KEY=$(echo "$RESP" | jq -r .data.r2Key) PUBLIC_URL=$(echo "$RESP" | jq -r .data.publicUrl) # 3) PUT the file to uploadUrl (expires in 10 min) curl -X PUT -T bottle.jpg -H "Content-Type: image/jpeg" "$UPLOAD_URL" # 4) Probe dimensions locally, then finalize with width/height WIDTH=$(sips -g pixelWidth bottle.jpg | awk '/pixelWidth/{print $2}') # or: identify -format "%w" bottle.jpg HEIGHT=$(sips -g pixelHeight bottle.jpg | awk '/pixelHeight/{print $2}') # or: identify -format "%h" bottle.jpg curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ -H "Content-Type: application/json" \ -X POST "https://api.oeave.com/agent/v1/projects/$PID/assets/finalize" \ -d "{\"r2Key\":\"$R2_KEY\",\"publicUrl\":\"$PUBLIC_URL\",\"sha256\":\"$SHA\",\"fileName\":\"bottle.jpg\",\"contentType\":\"image/jpeg\",\"fileSize\":$(stat -f%z bottle.jpg),\"width\":$WIDTH,\"height\":$HEIGHT,\"variants\":[\"depth\"]}" ``` The finalize response is `202` and includes `pending[].taskId` — poll at `/tasks/:id`. Use `variants: ["depth"]` only for images where the depth map matters (mood shots, product heros) — it's a metered Replicate call. **Always send `width` and `height` at finalize for images.** The schema marks them optional, but any asset referenced from `style.desktop.brandGraphic.images` (or any other srcSet-consuming location) is validated against a schema that requires them — you'll hit `Object is missing the required field 'height'` on the downstream PATCH, not on finalize. Probe dimensions locally before finalizing. For SVGs, use the `viewBox` dims or a sensible nominal (e.g. 1000×1000). **Uploads are deduplicated by sha256, and you cannot fix metadata after the fact.** `POST /assets/uploads` with a previously-seen sha256 returns `{reused: true, assetId}` and skips the PUT — re-finalizing with new `width`/`height` is a no-op. The asset row's metadata is frozen at first finalize. **The `agent:full` scope bundle does NOT include `assets:delete`** (or `threads:delete` / `fibers:delete`). If you finalize an asset with wrong metadata, there's no recovery via the API — your only options are to re-encode the file to change the sha256 (e.g. `ffmpeg -i in.webp -c:v libwebp -q:v 85 out.webp`, `sips -s format png in.png --out out.png`, or appending a comment to an SVG) and upload the new variant, or ask the user to delete it through the UI. Get finalize right the first time. ### 5b. Creating a fiber Refer to `GET /docs/fiber-kinds` for exact shapes. Shape of a fiber create: ```bash curl -s -H "Authorization: Bearer $OEAVE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -X POST "https://api.oeave.com/agent/v1/projects/$PID/fibers" \ -d '{ "kind": "featureCard", "data": { "title": "Dual-layer insulation", "text": "24h cold, 12h hot — tested in the Alps.", "icon": { "assetId": "as_abc" } } }' ``` Response is `202`. `data` is the stored fiber (fully hydrated). `pending[]` lists the embedding task. You can immediately reference `data.id` in thread components — you don't have to wait for embedding to finish. **Use `kind` names (strings), not numbers** — e.g. `"featureCard"`, `"image"`, `"threeDModel"`. See `/docs/fiber-kinds` for the canonical list. ### 5c. Updating a fiber Merge (default) — only fields you send are replaced: ```bash curl -X PATCH "https://api.oeave.com/agent/v1/projects/$PID/fibers/$FID" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -H "If-Match: 1713000000000" \ -d '{"data": {"text": "Improved wording."}}' ``` - `If-Match` is the version from the prior GET (equals `updatedAt`). 409 if someone else wrote first. - `"op": "replace"` to overwrite `data` wholesale. - `"skipReembed": true` to avoid burning embedding tokens for cosmetic changes. - `"embedding": { "mode": "auto"|"custom"|"none", "questions": ["…"], "force": false }` — control how the embedding is generated. See §5c-bis. ### 5c-bis. Controlling fiber embeddings Every fiber that gets created or has its `data` updated triggers a background `embed_fiber_plan` task that splits the fiber's text into chunks, generates HyDE-style questions per chunk, and stores 1536-dim vectors in `fiberEmbeddings`. You can shape that pipeline three ways: pre-supplied questions, a hash-skip on unchanged content, and a force flag. **The `embedding` payload** (accepted on `POST /fibers`, `PATCH /fibers/:fid`, and `POST /fibers/:fid/reembed`): ```jsonc { "embedding": { "mode": "auto", // "auto" (default) | "custom" | "none" "questions": ["How long does the battery last?", "..."], "force": false // default false } } ``` `POST /fibers/:fid/reembed` also accepts the same fields at the top level (no `embedding` envelope) since the request has no other body — pick whichever shape you prefer. **`mode` semantics:** | `mode` | Behavior | |---|---| | `"auto"` | LLM authors 3–5 questions per chunk (default — matches legacy behavior). | | `"custom"` | Embed your `questions` array verbatim alongside every chunk. Required when you want the search index to retrieve the fiber against specific phrasings (e.g. internal taxonomy, FAQ-style retrieval). Up to 20 questions; empty/whitespace strings are dropped. Sending `questions` without `mode` is treated as `"custom"`. | | `"none"` | Embed chunk text only, no questions. Use for fibers where the canonical text is already the optimal retrieval surface (raw transcripts, structured specs). | **Hash-skip on unchanged content.** Each successful embed stores a content fingerprint on the fiber. The next reembed call computes the same fingerprint and short-circuits if it matches — the response is still 202, but the task finishes immediately with `result: { skipped: "unchanged" }`. This makes idempotent "reembed if needed" loops cheap. The fingerprint covers both the chunk text and the question config (mode + custom questions), so changing only the question mode still triggers a real rebuild. The PATCH path automatically clears the fingerprint when `data` changes, so a fiber edit always re-embeds (unless you also pass `skipReembed: true`). **`force: true`** bypasses the hash skip. Use it when you've changed something that doesn't bump the fingerprint — e.g. an embedding model rollout, a chunking-rule fix, or you just want a clean rebuild. ```bash # Reembed only if content changed (no-op if cached) curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/fibers/$FID/reembed" \ -H "Authorization: Bearer $OEAVE_API_KEY" # Reembed with custom retrieval questions curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/fibers/$FID/reembed" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{"mode":"custom","questions":["How fast does this charge?","Is it waterproof?"]}' # Force a rebuild even if cached curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/fibers/$FID/reembed" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{"force":true}' # On create — pre-supply the retrieval questions curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/fibers" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{ "kind": "faq", "data": {"question":"Is it dishwasher safe?","answer":"Top rack only."}, "embedding": { "mode": "custom", "questions": ["Can I put it in the dishwasher?", "Will it warp in a dishwasher?"] } }' ``` Poll the returned `taskId` to see whether the run actually re-embedded — `result.skipped === "unchanged"` means the cache hit, `result.indexed` is the chunk count when it ran for real. **What makes a good `questions` array.** The questions are concatenated with the chunk text and embedded together — they pull the fiber into retrieval whenever a user (or another agent) phrases their search the same way. Treat them as the index entries you'd file the fiber under, not as comprehension prompts. Aim for: - **Real user phrasings, not your taxonomy.** Mirror how a buyer/operator/dev would actually type the question in a chat box or a search bar. "How long does the battery last?" beats "What is the battery duration specification?". - **Cover the variants.** Include synonyms, abbreviations, and the negative form. For a waterproofing fiber: `"Is it waterproof?" / "Can I take it in the shower?" / "What's the IP rating?" / "Will it survive rain?"`. - **Anchor on the noun the user knows.** Brand name, product name, or feature name as it's actually spoken. "Does the Stanley Quencher fit a cup holder?" out-retrieves "Does this fit a cup holder?". - **Mix breadth and specificity.** 2–3 broad-topic questions plus 1–2 sharp specifics; both shapes show up in real traffic. - **One thought per question.** "Is it fast and durable?" doesn't retrieve well — split into two. - **3–5 is the sweet spot.** Up to 20 is allowed, but past ~6 you mostly add noise. Quality over quantity. Avoid: - **Restating the title.** "What is X?" is what the chunk text already says — you're spending tokens on a duplicate. - **Yes/no without the topic.** "Does it do that?" matches everything; include the noun. - **Marketing voice.** "Why is our insulation industry-leading?" doesn't match what users type — write what *they* would. - **Stacking near-duplicates.** Two questions that differ only by a word add little. Use the slot for a different angle (price, comparison, durability, install). Worked examples: ```jsonc // featureCard fiber: "Dual-layer insulation, 24h cold / 12h hot" { "embedding": { "mode": "custom", "questions": [ "How long does the bottle keep things cold?", "Will it keep coffee hot for a workday?", "Does it sweat or condense on the outside?", "Is the insulation vacuum sealed?" ]}} // faq fiber: "Yes — top-rack dishwasher safe; hand-wash the lid." { "embedding": { "mode": "custom", "questions": [ "Can I put it in the dishwasher?", "Is the lid dishwasher safe?", "Will dishwashing warp the bottle?", "How do I clean it?" ]}} // pricing fiber: "Pro tier $29/mo, includes X / Y / Z" { "embedding": { "mode": "custom", "questions": [ "How much does the Pro plan cost?", "What's included in Pro vs Free?", "Is there a monthly or annual option?", "Do you offer a free trial?" ]}} // caseStudy fiber: "Acme cut churn 40% with our onboarding emails" { "embedding": { "mode": "custom", "questions": [ "Has anyone like Acme used this?", "What kind of churn reduction is realistic?", "Do you have a B2B SaaS case study?", "How long did Acme take to see results?" ]}} ``` Rule of thumb: read the chunk, imagine three different people who'd want to find it, and write down what each of them would actually type. If you can't picture the searcher, fall back to `mode: "auto"` and let the LLM pick. ### 5d. Building threads A thread is a title + ordered components. Components are either **fiber-backed** (pass `fiberIds` and the renderer hydrates slides from fibers) or **inline-authored** (carry their own content). ```bash # Create the thread TID=$(curl -s -X POST "https://api.oeave.com/agent/v1/projects/$PID/threads" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{"title":"How it works","funnelStage":"education"}' | jq -r .data.id) # Append components one at a time curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/threads/$TID/components" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{"component":{"kind":"text","richText":"

Step by step

"}}' curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/threads/$TID/components" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{"component":{"kind":"carousel","fiberIds":["f_step1","f_step2","f_step3"]}}' curl -X POST "https://api.oeave.com/agent/v1/projects/$PID/threads/$TID/components" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -d '{"component":{"kind":"cta","label":"Get yours","href":"https://brand.com/buy"}}' ``` Alternatively, include `components[]` in the initial POST. Component `id` is server-generated if omitted on every write path (per-component POST, thread POST with inline `components`, and thread `PATCH op:"replace"`) — grab it from the response. **Always preserve component ids when round-tripping.** When you GET a thread, mutate components, and PATCH them back, keep each component's `id` field intact. The renderer keys its background-texture cache on `id`; a missing or empty `id` used to ship to the CDN and crash the embed at runtime. The API now backfills missing ids on write, but agent-side stability is still the cleaner contract — if you drop ids during a mutation, the next response will hand you fresh ones and any external link to a specific component (analytics, deep links) will break. **Thread-level PATCH-replace** is the pragmatic way to edit a thread's components (see the last paragraph of this section for details): ```bash curl -X PATCH "https://api.oeave.com/agent/v1/projects/$PID/threads/$TID" \ -H "Authorization: Bearer $OEAVE_API_KEY" -H "Content-Type: application/json" \ -H "If-Match: $VERSION" \ -d '{"op":"replace","components":[ /* full new list */ ]}' ``` **`funnelStage` values** (used by suggestions and thread ordering): `awareness`, `education`, `validation`, `decision`, `conversion`. **Carousel / carouselHero only hydrate SLIDE MEDIA from fibers that actually carry media.** That means `image` (imageSrc), `video` (videoSrc), `threeDModel` (modelSrc), plus any fiber kind whose schema exposes an image-ish field and has it populated: `brandStory.image`, `featureCard.icon`, `useCase.image`, `testimonial.image`, `caseStudy.image`, `resource.image`, `pressMention.logo`, `behindTheScenes.media`. Purely text-shaped fibers — `faq`, `socialProof`, `coreValues`, `contactInfo`, `comparison`, `pricing`, `technicalSpecification`, `howItWorks`, `problemStatement`, `designPhilosophy`, `roadmap`, `targetAudience`, `benefitCard`, `setupGuide`, `timeline`, `legal`, `personalization`, `guarantee`, `bundle`, `availability`, `accessory`, `externalPage` — will still become slides, but with no background image. They render as captions on an empty surface and look sparse. Choose the right component for the content: | Content shape | Component | Notes | |---|---|---| | Short prose, value propositions, "why we built it" | `text` (`{kind:"text", richText:"..."}`) | **Default for simple text.** Auto-picks a background from `style.desktop.brandGraphic.images`. Override with `backgroundGraphics`. Prefer this over `cards` for narrative blocks. | | Structured card grid (3–6 parallel tiles) | `cards` with inline `cards:[{title, richText}]` | Reserve for genuinely grid-shaped content. | | Pricing tiers | `pricing` with inline `plans:[...]` | Not fiber-backed; inline plans. | | Comparison matrix | `table` with inline `rows` | Also not fiber-backed. | | Image / video / 3D story slides | `carousel` / `carouselHero` with `fiberIds` of image/video/3D fibers | Mix in screenshot fibers to carry the visual. | | Standalone image or model | `image` / `model3d` with inline `src: {assetId}` | Single-slide form. | **Hero anchors need a visual.** A `carouselHero` with only a title + a text-only fiber will render with no media. Pair every `carouselHero` with at least one image (or video / 3D) fiber in `fiberIds`, or upload an image and add it to the underlying fiber's optional `image` field. **Starter thread shapes that work.** Use these as templates — they avoid the empty-media pitfall and land on funnel stages that the app already understands. | Funnel stage | Good shape | |---|---| | `awareness` | `carouselHero`(hero image fibers) → `text`(problem framing) → `text`(headline stats) → `carousel`(3-5 product/mood images) → `text`(positioning) → `cta` | | `education` | `carouselHero`(UI/product shots) → alternating `text` + `carousel` blocks, one per step → closing `text`(capability summary) → `cta` | | `validation` | `carouselHero`(hero + one screenshot) → 2-3 `text` blocks ("us vs. …" narratives) → `carousel`(screenshots) → `text`(audience / outcomes) → `cta` | | `decision` | `carouselHero`(hero + callout shot) → `pricing`(inline `plans`) → several `text` blocks (FAQ entries) → `cta` | | `conversion` | `carouselHero`(hero + dashboards) → `text`(vision / roadmap) → `text`(values) → `carousel`(screenshots) → `text`(contact / skill pointer) → `cta` | **`richText` accepted syntax.** The renderer parses a narrow HTML subset plus markdown. Reliable tags: `` / ``, `` / ``, ``, `