From 64fb65a6fa09be0445c63f7f6fa79d2272adb2fa Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Fri, 20 Nov 2026 13:59:46 -0800 Subject: [PATCH] Controllers are gone, and plan.org is the one list raea's no-controllers and one-plan branches (docs/projects.feature PJ9, docs/plan.feature PL8) change what the skill teaches: - Standing decisions are taste lines: the person's, the workspace's and the project's taste.ts, with a check when one can hold it (rule_add in the app). A decision for now is asked in the chat or with feed_propose. The controller verb, the controller fields and the five controller tools are gone from SKILL.md, collaborate.md, delivery.md and sound.md. - plan.md: plan.org is the only list (the brief holds no tasks, a message isn't a task). Keywords are the file's own #+TODO: words, and the app writes TODO | DONE DROPPED. A task waiting on the person carries its item, and their approval of that item or any later version closes it. :LINK: and #+LINK_STATES: keep a task in step with another tracker, and checkPlan says what to fix. - An object's build plan is NAME.parts.ts (raea spec --as parts). - The references (cli, feed, files, sdk) and the guide copies are regenerated with tools/skills.sh gen-into, in an export of raea main with both branches, against the app's one-plan branch. directory/ is rebuilt. --- directory/skills/raea/3d/blender.md | 3 +- directory/skills/raea/3d/prompts.md | 12 +-- directory/skills/raea/3d/scenes.md | 4 +- directory/skills/raea/SKILL.md | 59 +++++------ directory/skills/raea/collaborate.md | 12 +-- directory/skills/raea/craft/ROUTER.md | 6 +- directory/skills/raea/craft/verbs/adapt.md | 2 +- directory/skills/raea/craft/verbs/layout.md | 2 +- directory/skills/raea/delivery.md | 4 +- directory/skills/raea/motion/delivery.md | 16 +-- directory/skills/raea/motion/match-cuts.md | 10 +- directory/skills/raea/motion/rendering.md | 17 +++- directory/skills/raea/motion/sound.md | 10 +- directory/skills/raea/plan.md | 102 +++++++++++++------- directory/skills/raea/reference/cli.md | 21 ++-- directory/skills/raea/reference/feed.md | 59 +---------- directory/skills/raea/reference/files.md | 45 +++------ directory/skills/raea/reference/sdk.md | 2 +- directory/skills/raea/sound.md | 4 +- skills/raea/3d/blender.md | 3 +- skills/raea/3d/prompts.md | 12 +-- skills/raea/3d/scenes.md | 4 +- skills/raea/SKILL.md | 49 +++++----- skills/raea/collaborate.md | 12 +-- skills/raea/craft/ROUTER.md | 6 +- skills/raea/craft/match-cuts/thirds.ts | 2 +- skills/raea/craft/verbs/adapt.md | 2 +- skills/raea/craft/verbs/layout.md | 2 +- skills/raea/delivery.md | 4 +- skills/raea/motion/delivery.md | 12 +-- skills/raea/motion/match-cuts.md | 10 +- skills/raea/plan.md | 102 +++++++++++++------- skills/raea/reference/cli.md | 16 +-- skills/raea/reference/feed.md | 58 +---------- skills/raea/reference/files.md | 45 +++------ skills/raea/reference/sdk.md | 2 +- skills/raea/sound.md | 4 +- 37 files changed, 325 insertions(+), 410 deletions(-) diff --git a/directory/skills/raea/3d/blender.md b/directory/skills/raea/3d/blender.md index 281481f..e7b6498 100644 --- a/directory/skills/raea/3d/blender.md +++ b/directory/skills/raea/3d/blender.md @@ -202,8 +202,7 @@ import { BlenderShot } from "raea/blender/shot"; server's env. It can otherwise send prompts, code and screenshots to its author. - `generate_3d` can cost the person a credit, and makes one object only; `raea gen` is the generation route. Ask first. -In the raea app, a workspace gives it to the feed's agents with a controller's servers field holding -`uvx mcp-for-blender` (`raea controller set PATH VALUE`). +`raea skills install --agent NAME` adds it to that agent as an MCP server (`--no-mcp` leaves it out). ## Licences diff --git a/directory/skills/raea/3d/prompts.md b/directory/skills/raea/3d/prompts.md index 4cb0c23..ad6f823 100644 --- a/directory/skills/raea/3d/prompts.md +++ b/directory/skills/raea/3d/prompts.md @@ -20,7 +20,7 @@ Where these texts come from: the published Blender + Claude workflows. ## What to do -1. Write the brief from the template (section 1). Write a `plan.ts` for every hero object. +1. Write the brief from the template (section 1). Write a `NAME.parts.ts` for every hero object. 2. Start the builder with the builder prompt (section 2), filled from the brief. 3. After every stage and every fix, run step R: the review sheets, then the judge prompt (section 3) in a new context and `raea judge` on the same sheets. @@ -29,7 +29,7 @@ Where these texts come from: the published Blender + Claude workflows. The brief is data, in three files: - `brief.ts` for the scene, made with `brief()` from `raea/brief`. -- A `plan.ts` for each hero object, made with `plan()`. +- A `NAME.parts.ts` for each hero object, made with `parts()`. - For an interior, the room plan that `checkLayout` reads (`raea/room`). Fields that have no schema yet go in `sections` as text. @@ -72,12 +72,12 @@ Each generated object needs a reference picture made from this template: > light, plain pale grey seamless background, the whole object in frame with margin, three-quarter view from slightly > above, sharp focus, no people, no text, no brand names, no logos. -Each hero object gets a plan. Its fields are the frozen contract that `raea solid info --expect` and the judge check +Each hero object gets its parts (NAME.parts.ts). Its fields are the frozen contract that `raea solid info --expect` and the judge check against: ```ts -import { plan } from "raea/brief"; -export default plan({ +import { parts } from "raea/brief"; +export default parts({ concept: { what: "coin-op tumble dryer, stacked pair", style: "worn 1990s commercial", size: 1.9, seenFrom: 1.2, material: "enamelled steel" }, parts: { @@ -104,7 +104,7 @@ finished scene must read as the same place, the same objects and the same light. invent in the same world. brief.ts notDoing is a hard list: add nothing on it, and nothing the brief doesn't name. ORDER OF WORK (one stage at a time; a stage that fails its check is fixed before the next one starts) -0. Plan. Every object row in brief.ts has a route, a real size and, for each hero, a plan.ts with its part tree and +0. Plan. Every object row in brief.ts has a route, a real size and, for each hero, a NAME.parts.ts with its part tree and connection map. If any is missing, write it first, from how the real thing is built: look up the real product. 1. Space. Block the room as boxes at real size. Place furniture with place() from raea/3d (on, against, beside, near, apart, facing, align, clear), never typed coordinates; its `found` must be empty. Check: `raea run checks.ts` diff --git a/directory/skills/raea/3d/scenes.md b/directory/skills/raea/3d/scenes.md index 0713d00..b066141 100644 --- a/directory/skills/raea/3d/scenes.md +++ b/directory/skills/raea/3d/scenes.md @@ -28,7 +28,7 @@ The brief template, the builder prompt and the judge prompt to paste are in `bev - Printed matter. - Motion. - Budget: generation cents and judge rounds. -- Each hero object gets a `plan.ts` (`plan()`) with its concept (what, style, size, seenFrom, material) and parts, each +- Each hero object gets a `NAME.parts.ts` (`parts()`) with its concept (what, style, size, seenFrom, material) and parts, each with a role, a level (primary, secondary, tertiary), a parent, a count and `near` detail. Below it, add a connection map with one line per joint: `door <-> cabinet hinge side touches`. - Write the plan from how the real thing is built: look up the product, the catalogue or a drawing. @@ -65,7 +65,7 @@ check names a script (`bevy/blender`). It never places, lights, frames, material ### 3. Build, one stage at a time; a stage that fails its check is fixed first -0. **Plan.** Every object row has a route and a real size, and every hero has a `plan.ts`. +0. **Plan.** Every object row has a route and a real size, and every hero has a `NAME.parts.ts`. 1. **Space.** Block the room as boxes at real size. Place furniture by relations, not typed coordinates: `place({ room, objects, rules })` from raea/3d. Rules are `on`, `against` a wall, `beside`, `near`, `apart`, `facing`, `align` and `clear` (floor kept free in front). It returns each object's `center`, `base` and `yaw`, diff --git a/directory/skills/raea/SKILL.md b/directory/skills/raea/SKILL.md index 0eca9d8..a72131d 100644 --- a/directory/skills/raea/SKILL.md +++ b/directory/skills/raea/SKILL.md @@ -3,7 +3,7 @@ name: raea description: Make video, motion graphics, games and 3D scenes with raea, the Render Anything Engine, by writing React/TypeScript compositions with raea and rendering them on the GPU with the raea CLI (or playing games live). Use when the user names raea, or wants 3D scenes (Bevy materials, lights, physics, Gaussian splats), 3D placed into footage (matchmove), a playable game, footage cut by its words, cuts timed to a song's beat map, or foley and instruments made locally on the Mac. Also for writing or fixing 3D TSX (Camera3d, Mesh3d, lights, materials, glTF models, post effects, an ECS world), a 3D render or play that looks wrong, extending raea's Bevy SDK, rendered video, captions and motion graphics from code, and frames rendered headlessly. metadata: raea-tested-against: 0.1.0-rc1 - raea-verbs: render play run check init cut song guide skill skills app controller workspace project spec doctor next library setup gen context brand scene splat blender + raea-verbs: render play run check init cut song guide skill skills app workspace project spec doctor next library setup gen context brand scene splat blender --- # raea @@ -72,7 +72,7 @@ Generated from the code by `tools/skills.sh gen`, so they're current. Read the o - [reference/cli.md](reference/cli.md): every `raea` verb, its flags and where it runs (`raea help` prints the same). - [reference/feed.md](reference/feed.md): the raea app's tools for an agent it launches, and which need its page. - [reference/files.md](reference/files.md): a workspace's and a project's files, what lives in `~/.raea`, and each - spec's fields (brief.ts, NAME.script.ts, taste.ts, plan.ts, controllers/ID.ts). + spec's fields (brief.ts, NAME.script.ts, taste.ts, NAME.parts.ts). - [reference/sdk.md](reference/sdk.md): what each `raea` import gives a composition. - [reference/app.md](reference/app.md): driving the raea app's window over MCP, as a person would (HOST). - [reference/platforms.md](reference/platforms.md): each network the app publishes to: shapes, lengths, file and @@ -95,7 +95,7 @@ task needs. | an app's interface (web or native) | [apps.md](apps.md) | | generated images, video, sound or meshes | [gen.md](gen.md) | | the export, the share copy, platform specs, posting a deliverable | [delivery.md](delivery.md) | -| working with the person in the raea app: the feed, controllers, the editor, boards | [collaborate.md](collaborate.md) | +| working with the person in the raea app: the feed, rules, the editor, boards | [collaborate.md](collaborate.md) | | planning the work and keeping its tasks: the project's plan.org, the person's to-do list | [plan.md](plan.md) | | checking a cut against the person's taste and rules, reading their notes on a sound, or teaching their fingerprint | [fingerprint.md](fingerprint.md) | @@ -109,12 +109,12 @@ an explain, a story, a game or a tool has to do; `craft/verbs/` has one file per Work lives in a workspace: a git repo under raea.root (`git config --global raea.root`; unset, `~/Studio` where workspaces already are, else `~/Documents/raea`, or `~/raea` when iCloud keeps Documents), one per studio or client, -holding projects and controllers. In the raea app a project shows as a channel. +holding projects and the workspace's taste.ts. In the raea app a project shows as a channel. - `raea workspace init NAME` makes one; `raea workspace adopt DIR` makes an existing folder one. `raea workspace` shows it (`--json` for the projects and their paths). - `raea project new NAME` adds a project: its folder with `brief.ts`, `AGENTS.md`, `compositions/`, `components/`, - `controllers/`, `assets/`, `artifacts/` and `out/`. The workspace's `shared/` has the same five folders, which any - project imports from as `@shared/components/NAME`. A project can live inline or as its own repo + `assets/`, `artifacts/` and `out/`. The workspace's `shared/` has the same folders but `out/`, which any project + imports from as `@shared/components/NAME`. A project can live inline or as its own repo (`raea project split NAME`, `raea project join NAME`); both keep its history. - Work in the project's folder. Footage and other media go in `assets/` (`media/` in a project made before the layout), renders in `out/`. @@ -124,34 +124,29 @@ holding projects and controllers. In the raea app a project shows as a channel. - `raea context .` in the project prints everything to read first, in order: the person's taste (`~/.raea/taste/taste.ts`; a line there beats any guide's default), the workspace's taste, the brief, the look, the - workspace's controllers, the craft floor and each of the brief's modes' guides. Read all of it. In the raea app, + craft floor and each of the brief's modes' guides. Read all of it. In the raea app, `rules_read` lists every rule the work follows, the project's own `taste.ts` first ([collaborate.md](collaborate.md)). - Run it once a session. If it refuses, say so in one line ("raea context failed: its message; reading the brief and - controllers directly") and read `brief.ts`, any `*.script.ts`, `~/.raea/taste/taste.ts` and `raea controller ls` - yourself. A `CONTEXT_STALE` line means `raea doctor` finds files from another version: run `raea doctor --fix`. + taste directly") and read `brief.ts`, any `*.script.ts`, `~/.raea/taste/taste.ts` and the workspace's and the + project's `taste.ts` yourself. A `CONTEXT_STALE` line means `raea doctor` finds files from another version: run `raea doctor --fix`. - With no request in hand, `raea next` lists the two or three useful next steps from the brief, the compositions, the renders and their checks. Offer them; never run one unasked. -- The controllers (`raea controller ls`, `raea controller get PATH`) are the workspace's settings and workflows: - delivery specs, who reviews what, the tools every agent gets. Work to them. Change one only when the person asks: - `raea controller set PATH VALUE` (each change is a commit). -- A controller is not a feed item. A feed item is one piece of work (a render, a still, a question): the person - reviews it once and a note on it is answered by its next version. A controller is a standing decision every agent - reads before it starts, so changing it changes all the work after. If the person would say it again on the next - piece ("always 9:16", "Grade checks every cut"), it belongs in a controller; if it's about this piece only, it's a - note. When the work needs such a decision from the person, put the controller in front of them with the feed's - `controller_post` (its id, the fields as group.field, a line on what you need decided) rather than asking in prose; - a controller you make with `controller_write` reaches their feed on its own. Fields are typed (toggle, choice, - number, text, list, agents, channels, workflow, servers, skills, rule; reference/files.md), so put what they'll - adjust in fields, one controller per concern. A style preference with no fields to set ("words never cover the - action") is a rule instead: `rule_add` in the app, or a line in the project's `taste.ts`. -- A `rule` field is a line every piece is held to and the check that holds it: one of raea's by name with its values, - or a `.ts` check written with `raea/check` (craft/ROUTER.md, step 7). `raea check PROJECT` runs every rule that - applies, with raea's floor and the person's taste, and says what waits for a render. +- Standing decisions are taste lines: the person's taste, the workspace's `taste.ts` and the project's `taste.ts` hold + what holds for every piece (the delivery spec, the loudness, "always 9:16", "words never cover the action"). A line + says it in words and, when something can hold it, names its check: one of raea's forms or checks by name with its + values, or a `.ts` check written with `raea/check` (craft/ROUTER.md, step 7). Work to them. Add or change one only + when the person says so: `rule_add` in the app, or a line in the project's (or workspace's) `taste.ts`. + `raea check PROJECT` runs every line that applies, with raea's floor, and says what waits for a render. +- A taste line is not a note. A feed item is one piece of work (a render, a still, a question): the person reviews it + once and a note on it is answered by its next version. If the person would say it again on the next piece, it's a + taste line; if it's about this piece only, it's a note. When the work needs a decision from the person, ask it in + the chat with your best guess (or `feed_propose` what you'd make), rather than burying it in a long reply. - If the brief isn't shaped (no `believe`, no `mode`), shape it before making anything: ask who it's for and the one thing they should believe, or write your best guess and add its field to the brief's `assumed` list. - For a pitch, an explain or a story, plan first: write the deliverable's storyboard as `NAME.script.ts` beside the brief (`export default script({...})` from "raea/brief": scenes of beats, what's on screen and what each scene must - land; its fields are in reference/files.md), name it on the deliverable, and add a task "storyboard approved" tagged `gate`. `raea spec NAME.script.ts` + land; its fields are in reference/files.md), name it on the deliverable, and add its task to plan.org with the + storyboard's feed item on it once posted ([plan.md](plan.md)): their approval closes it. `raea spec NAME.script.ts` checks it. Render nothing until the person approves it (PERSON). - Show a plan as what it will be, in this order: previz (a rough, fast raea render of the blocking, timing and camera: grey shapes, placeholder type, no polish; it is the plan, not the piece, so the gate allows it), else a @@ -270,6 +265,16 @@ least sure of. Once they've answered, `--tally` makes the answers evidence. next tool call and keeps your turn from ending until you have it (where there is no hook, follow the file with `tail -n0 -F FILE` or your harness's monitor). Answer each: it may change what you're doing. Without the app, `raea show` opens the file in the Mac's own viewer and says so; take the person's notes as text then. +- When one picture holds several things (a contact sheet, a side by side, a before and after, a grid of props or + characters), label each instead of naming them by position in the title or your message. A label is a tag of a few + words that stands beside the picture, never on it, and points at its place when the person's pointer is on it; give + it a paragraph only where a tag isn't enough. In the app, `feed_post` takes `labels`: each `{ text, detail?, box: + [x0, y0, x1, y1] }` or `point: [x, y]` in the picture's own 0-1, with `frame` for a storyboard's still, `t` (and + `to`) for a film's seconds, or `part` for a scene's part. Outside it: `raea show sheet.png --label "0,0,.5,1 v1, hook + first" --label ".5,0,1,1 v2, product first" --detail "Opens on the product for two seconds, then the hook."` (each + `--label` is the place, then its tag; a `--detail` is the paragraph of the `--label` before it). A sheet `raea media + sheet` made comes labelled with each cell's time or file; to say more, edit the tags and paragraphs in its + `OUT.labels.json` before you show it. - When you need the person to choose or fill something in (pick an opening, rank cuts, set a price), post an artifact: a React `.tsx` of your own, `feed_post` with `type: "artifact"`, the file, and an `ask` line. The app builds it and runs it sandboxed in the feed. Its default export is the component. It imports `react`, `@raea/app` and its own @@ -333,7 +338,7 @@ least sure of. Once they've answered, `--tally` makes the answers evidence. - A render is a standard MP4 but large: H.264 High and AAC on a Mac (VideoToolbox), H.264 Constrained Baseline and Opus on Windows and Linux (openh264), yuv420p on all. Hand over a share copy too, which any player takes: `ffmpeg -i film.mp4 -c:v libx264 -preset slow -crf 23 -maxrate 2600k -bufsize 5200k -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart film-share.mp4`. -- Deliver to the controllers' specs (sizes, platforms, loudness) when the workspace sets them; each network's shapes, +- Deliver to the taste's specs (sizes, platforms, loudness) when the workspace or project sets them; each network's shapes, lengths and UI zones are in [reference/platforms.md](reference/platforms.md), and [delivery.md](delivery.md) routes the rest (one composition per shape, cutdowns, tags, handing over). diff --git a/directory/skills/raea/collaborate.md b/directory/skills/raea/collaborate.md index d3fde87..fb09cb2 100644 --- a/directory/skills/raea/collaborate.md +++ b/directory/skills/raea/collaborate.md @@ -1,7 +1,7 @@ # Working in the raea app When the raea app launches you, its feed is where you and the person work together: you post what you make, they -look, play and leave notes, and the workspace's standing decisions live in controllers. Most tools here are PAGE (they +look, play and leave notes, and their standing decisions are taste lines (the rules). Most tools here are PAGE (they need the person's feed open); the rules tools are HOST (the app answers them with no page open). All are listed in full in [reference/feed.md](reference/feed.md); this file says when to reach for each. Headless, with no app, SKILL.md's steps 5 and 6 say what to do instead. @@ -10,21 +10,19 @@ full in [reference/feed.md](reference/feed.md); this file says when to reach for | ...then | Use | |---|---| | know what to make, as the project stands now | `feed_brief` (the brief.ts, current); in a workspace chat, `workspace_read` for its projects and agents | -| know what's planned, what's under way and what the person's message asks of you | `plan_read` (the project's plan.org: open tasks by id); each turn's prompt carries the same as `raea://plan/`, with the task the message is ([plan.md](plan.md)) | +| know what's planned and what's under way | `plan_read` (the project's plan.org: open tasks by id); each turn's prompt carries the same as `raea://plan/` ([plan.md](plan.md)) | | plan work of more than one step, or note what's left to do | `plan_add`: tasks under a stage heading, or under a task as subtasks, with checkboxes for small steps | | act on a round of notes the person sent on an item | plan it first: `plan_add` with the work in your words, each task `from` the notes it answers (`ITEM#COMMENT`, spaces between); `comment_task` `done` at once for a note that asks for nothing; then work the tasks ([plan.md](plan.md), "Notes from the person") | -| say you've started a task, or that it waits on the person | `plan_update` with `state` `making` or `review`; tick its checkboxes with `check` | +| say a task waits on the person (a pick, an approval) | `plan_update` with the `item` they're to look at: their approval of it, or of a later version, closes the task. Tick its checkboxes with `check` as you go | | finish a task, or drop one that no longer applies | `plan_close` with the item you posted (it stamps CLOSED and links the work), or `state: "dropped"` and why | | say what you'd make next and let the person choose before you spend the time | `feed_propose`: a planned item they accept, or don't | | show what you made | `feed_post`: a render, a still, audio or a game; a new version names the item it `replaces` and says in `changed` what changed | | let the person look around a 3D scene, a set of shots, or props and characters, and point at what is wrong in it | `feed_post` type `scene` with the scene's `.tsx` (or a component's, or a model); `files` adds more as a board (a storyboard's shots, a grid of props), `names` says what each is called. They move through it live, pin comments to points on its surfaces (marked mesh, shader, clipping or artifact; each tells you the point in the scene's space and where the part is written), and may move, draw and re-key parts in the file by hand: the next round you are sent lists what they changed, so read the file again and keep it | | read what's in the feed and the notes left on it | `feed_items` | | mark which items are deliverables, and for where | `item_tags` (key:value tags such as `platform:tiktok` become the project's Table columns; `export` makes it a deliverable), or `export`/`tags` on `feed_post` ([delivery.md](delivery.md)) | -| read the workspace's standing decisions (delivery specs, who reviews what) | `controllers_read`, before you start | -| have the person decide something that should hold for every piece from now on | `controller_post` with the fields and a line on why; a decision about one piece is a note on it, not a controller | -| add a standing decision the person asked for, change one field, or retire one | `controller_write`, `controller_set`, `controller_remove`, only when the person asks | +| have the person decide something before you go on | ask in the chat, with your best guess; or `feed_propose` what you'd make and let them accept it. Once they've answered, a decision that holds for every piece from now on is a rule (`rule_add`, below); one about this piece only is a note on it | | know the rules this project's work follows (the project's own, the workspace's house rules, the person's taste) and which fingerprint judges it | `rules_read`, before you start and again before you post: the person changes rules in Fingerprint › Rules while you work | -| keep a style preference the person states for all the work from now ("make this a rule", "always…", "never again…", "note that for later") | `rule_add` to the project's rules, with `why` and `when` it applies, and `axis` when a fingerprint axis guards against it. It holds at once and waits in Fingerprint › Rules for them to keep. A setting with fields (delivery sizes, who reviews) is a controller instead, and their own taste they change themselves | +| keep a standing decision the person states for all the work from now ("make this a rule", "always…", "never again…", "deliver 9:16 and 1:1", "note that for later") | `rule_add` to the project's rules, with `why` and `when` it applies, a check when one can hold it, and `axis` when a fingerprint axis guards against it. It holds at once and waits in Fingerprint › Rules for them to keep. Their own taste they change themselves | | hold a render, a still, a sound or a game to every rule before you post it | `rule_check` with the file, and your `verdicts` on the rules nothing measures after you've looked; fix what it says broke and where, then `feed_post` | | work on what the person has open in the composition editor ("this", "here", "the selected one") | `editor_selection` first, then `editor_edit`: their undo takes it back, and it saves with their changes | | show a plan before making it | previz first: a rough raea render of blocking, timing and camera, `feed_post` watch. Else a storyboard: key frames as one `feed_post` look with `files` in order. Else the script: `feed_post` read with its `NAME.script.ts`, which the feed shows as a screenplay and as an A/V table (give each beat its `seconds` and the table is timed); a `.md` reads as prose | diff --git a/directory/skills/raea/craft/ROUTER.md b/directory/skills/raea/craft/ROUTER.md index 93e724e..54244a2 100644 --- a/directory/skills/raea/craft/ROUTER.md +++ b/directory/skills/raea/craft/ROUTER.md @@ -57,9 +57,9 @@ leads. raea will add modes as its work grows; `raea context` says when a brief n 5. **The floor:** read it right before you edit. 6. **Make it.** 7. **Evidence:** run `raea check`, look at the frames, critique against the mode's guide, fix, and look again. - A line the work must keep every round is a rule, not a reminder: a field `{ label, type: "rule", check, values }` - in the project's controller, whose check is one of raea's by name (`text-above`, `loudness`) or a `.ts` check you - write with `raea/check` (`check({ id, text }, (world, frame, values) => ...)` and `found(...)`). `raea check + A line the work must keep every round is a rule, not a reminder: a line `{ text, check, values }` in the project's + taste.ts, whose check is one of raea's by name (`text-above`, `loudness`) or a `.ts` check you write with + `raea/check` (`check({ id, text }, (world, frame, values) => ...)` and `found(...)`). `raea check PROJECT` runs every rule on every composition and says what waits for a render. A quick edit (one value, one word, one cut) skips to the floor and makes the change. "This isn't working" means a diff --git a/directory/skills/raea/craft/verbs/adapt.md b/directory/skills/raea/craft/verbs/adapt.md index 0b1664f..0f11cf7 100644 --- a/directory/skills/raea/craft/verbs/adapt.md +++ b/directory/skills/raea/craft/verbs/adapt.md @@ -4,7 +4,7 @@ Notes like these: "we need it in 16:9", "a square one for the feed", "4:5 for In YouTube". The same piece made right for another size, length or platform; never a crop of the old one. ## Assess -- The controllers' delivery specs name the sizes, lengths and platforms; work to those. +- The brief's deliverables and the taste name the sizes, lengths and platforms; work to those. - For each size, find what no longer fits: type that wraps, a face cut off, a part in a platform's button zone, a hold that's too long for a shorter cut. diff --git a/directory/skills/raea/craft/verbs/layout.md b/directory/skills/raea/craft/verbs/layout.md index d7fa4d9..802642e 100644 --- a/directory/skills/raea/craft/verbs/layout.md +++ b/directory/skills/raea/craft/verbs/layout.md @@ -18,7 +18,7 @@ space", "the logo's lost". Where things sit in the frame and how much room each - One focal point per moment. Make it bigger or give it more room; make the rest smaller rather than moving it away. - Put parts on a grid: shared left edges, shared baselines, the same margin on every side (`raea guide motion/layout`). - Use the room on purpose: space around the focal point, not spread evenly across the frame. -- Keep text and faces inside the safe zones of every platform the controllers name. +- Keep text and faces inside the safe zones of every platform the brief or the taste names. ## Verify - Stills at the same frames, before and after (`raea render --at`), at ship size. The eye goes to the right place first. diff --git a/directory/skills/raea/delivery.md b/directory/skills/raea/delivery.md index c6591cc..1f3dc8d 100644 --- a/directory/skills/raea/delivery.md +++ b/directory/skills/raea/delivery.md @@ -1,7 +1,7 @@ # Delivery and publishing Getting finished work to the person and their platforms: the shapes and lengths each network takes, the export's -settings, the share copy, the controllers' delivery specs, the versions kept beside each other, and handing it to +settings, the share copy, the delivery specs in the taste, the versions kept beside each other, and handing it to the person, who publishes from the raea app's Publish view. The files under `motion/` are copies of raea's craft guides (`raea guide NAME` prints the same text). @@ -13,7 +13,7 @@ copies of raea's craft guides (`raea guide NAME` prints the same text). | a network's shapes, lengths, file and caption limits, and where its interface covers the frame | [reference/platforms.md](reference/platforms.md) | | rendering the video, stills, quality and bitrate, dark material, the person's hand edits | [motion/rendering.md](motion/rendering.md) | | the export's format, file names, the share copy | [SKILL.md](SKILL.md) ("7. Deliver") | -| a workspace's delivery spec (sizes, platforms, loudness) | `raea controller ls`, then the controller it names ([reference/files.md](reference/files.md) for its fields) | +| a workspace's delivery spec (sizes, platforms, loudness) | its taste lines: `raea context .`, or `rules_read` in the app (the person's, the workspace's and the project's taste.ts) | | the same piece in several shapes (9:16, 1:1, 16:9) | [motion/compositions.md](motion/compositions.md) | | keeping clear of a platform's UI zones | [motion/placement.md](motion/placement.md) | | posting a deliverable in the app: `feed_post` with `export` and key:value `tags` | [reference/feed.md](reference/feed.md) | diff --git a/directory/skills/raea/motion/delivery.md b/directory/skills/raea/motion/delivery.md index 3b935bf..49522b5 100644 --- a/directory/skills/raea/motion/delivery.md +++ b/directory/skills/raea/motion/delivery.md @@ -2,10 +2,10 @@ ## What to do -- Start from what's asked for. The brief's deliverables say the pieces; the workspace's delivery controller, when - there is one (`raea controller ls`, or `controllers_read` in the app), says the shapes, lengths, platforms, caption - rule and loudness for every piece. Work to it. When neither says where a piece goes, ask once with your best guess, - or write the guess and add it to the brief's `assumed`. +- Start from what's asked for. The brief's deliverables say the pieces; the taste (`raea context .`, or `rules_read` + in the app: the person's, the workspace's and the project's taste.ts) says the shapes, lengths, platforms, caption + rule and loudness every piece keeps. Work to it. When neither says where a piece goes, ask once with your best + guess, or write the guess and add it to the brief's `assumed`. - Make each shape as its own composition from the same scenes (`motion/compositions`), laid out for that shape: a vertical cut puts its type and faces where a vertical frame has room, it doesn't crop the wide one. Name them by shape (`launch-9x16`, `launch-1x1`, `launch-16x9`). @@ -16,10 +16,10 @@ - Keep text and faces out of the platform's UI zones for that shape (reference/platforms.md; `motion/placement` for how), then check the export against the platform: `raea check out/launch-9x16.mp4 --manifest out/render.json --shape 9:16 --platform tiktok`. -- Captions: burn them in for feeds that play without sound, unless the delivery controller says captions off; then +- Captions: burn them in for feeds that play without sound, unless the taste says captions off; then burn none, and leave the words file beside the export for the platform's own captions. -- Sound to -14 LUFS integrated with true peak at or below -1 dBTP: one `` per - composition does it (`motion/sound`). A spec that names another number wins. +- Sound to -14 LUFS integrated with true peak at or below -1 dBTP: raea's mix and master do it on every render + (`motion/sound`). A spec that names another number wins: `` sets it. - Render the export at `--quality master` (motion graphics and type) or `--quality high` (a film), and versions made for notes with no `--quality` flag; name it in lowercase letters, digits and hyphens, with its shape and length: `spring-launch-9x16-15s.mp4`. Each version is a new file beside the last, never written over it. @@ -71,7 +71,7 @@ exports and renders), so one file can't be right in both. vertical out as its own composition. - Text in the bottom quarter of a vertical frame, where every short-video network puts its caption and buttons. - A 15 s cutdown that is the first 15 seconds of the long cut, with no ending. -- Captions burned in on a piece whose delivery controller says captions off, or burned in twice: once by the piece, +- Captions burned in on a piece whose taste says captions off, or burned in twice: once by the piece, once by the platform's auto-captions the person turned on. - `final-v2-FINAL.mp4`, `Launch Video (1).mp4`, or a new render written over the version the person last saw. - Tags that change keys between items (`tiktok`, `platform:TikTok`, `network:tiktok`): the Table makes three columns. diff --git a/directory/skills/raea/motion/match-cuts.md b/directory/skills/raea/motion/match-cuts.md index 04bfdca..a00dcea 100644 --- a/directory/skills/raea/motion/match-cuts.md +++ b/directory/skills/raea/motion/match-cuts.md @@ -143,11 +143,11 @@ import { landsOnThirds } from "./match-cuts/thirds"; import film from "../film.chain"; export default landsOnThirds(film); -// controllers/rules.ts: the project's controller, holding the rule; its check is a path from this file (a note's ask -// names the same file in its `check`) -import { controller } from "raea/brief"; -export default controller({ title: "Rules", groups: [{ title: "The cuts", fields: [ - { label: "the cuts land on the thirds", type: "rule", check: "../checks/film-cuts.ts", values: { tolerance: 0.06 } }, +// taste.ts: the project's taste, holding the rule; its check is a path from this file (a note's ask names the same +// file in its `check`) +import { taste } from "raea/brief"; +export default taste({ title: "Rules", sections: [{ heading: "The cuts", rules: [ + { text: "the cuts land on the thirds", check: "checks/film-cuts.ts", values: { tolerance: 0.06 } }, ] }] }); ``` diff --git a/directory/skills/raea/motion/rendering.md b/directory/skills/raea/motion/rendering.md index cbae3d7..99fda4b 100644 --- a/directory/skills/raea/motion/rendering.md +++ b/directory/skills/raea/motion/rendering.md @@ -8,7 +8,10 @@ It measures clipped text, text under a platform's buttons, text over the face, captions on too briefly to read, caption contrast against the pixels behind them, frozen stretches, flashing past the limit, cues that miss their word, loudness, a sound that stops dead or (with `--words`) fights the voice, and encoder blotching in the darks. Each finding is ranked P0 to P3 - with its fix; it exits 1 while a P0 or P1 stands, and `-o check.json` writes them for the critique. An + with its fix; it exits 1 while a P0 or P1 stands, and `-o check.json` writes them for the critique. Fix every error + in one pass before rendering again. A finding that ends `[also in …]` was in the earlier export too: what you changed + didn't move it, so don't repeat that change; try another, or say why it stands. A note is for the person, not a + reason to render again. An exception in the composition (an unclamped value going NaN, keyframes out of order, a phrase `word()` can't find, a missing prop) fails the render and names the line. - **Watch it as a viewer would once the piece is close.** `raea check` measures; it can't judge a frame cropped too @@ -21,7 +24,10 @@ - **Without `--manifest`**, `raea render` writes the export alone, without the measurements `raea check` reads. Render another deliverable from its own file the same way (`raea render NAME.tsx -o NAME.mp4 --manifest NAME.json`) and check it. -- **Loudness** comes out at -14 LUFS integrated (±1) with true peak at or below -1 dBTP when `` is in the tree. +- **Loudness** comes out at -14 LUFS integrated (±1) with true peak at or below -1 dBTP: raea levels each line of + dialogue (the `voice` bus, or footage on no bus) to the same loudness and masters the piece, so don't measure lines + or set `gainDb` to level them, and don't master the voice outside raea. `gainDb` is for a deliberate change, on top + of raea's level. `` sets another target. ## Why @@ -45,9 +51,10 @@ looking again, finds more than a still per change and costs less. A video's bitrate follows its size and frame rate (about 20 Mbit/s at 1080p30, 80 at 4K30; VideoToolbox spends less on flat pictures), and `--kbps N` sets it. `--quality draft|high|master` (or 0..1: 0.6, 0.85, 0.95) asks for constant quality instead, each frame getting the bits it needs: `master` keeps thin type and hard vector edges clean at 4K -(about 31 Mbit/s on flat motion graphics). Blotching in dark areas is the encoder, not the composition: export dark -material as PNG frames (`RAEA_READBACK=rgba raea render piece.tsx -o piece.frames/`) and encode them with more bits for -the darks. A `NAME.frames/` folder is never committed, and raea's storage dry run lists it a day after +(about 31 Mbit/s on flat motion graphics). Blotching in dark areas is the encoder's or the footage's own, and on a +render made in a project `raea check` says which: the footage's is a note to pass on, never a reason to render again; +for the encode's, render with `--quality master`. Dark material can also go out as PNG frames +(`RAEA_READBACK=rgba raea render piece.tsx -o piece.frames/`). A `NAME.frames/` folder is never committed, and raea's storage dry run lists it a day after the render unless something names it. Which to ask for. A version made for notes (a cut to review, a shot that will be joined, a preview) takes no diff --git a/directory/skills/raea/motion/sound.md b/directory/skills/raea/motion/sound.md index 2a6fd6f..c5a9eff 100644 --- a/directory/skills/raea/motion/sound.md +++ b/directory/skills/raea/motion/sound.md @@ -36,11 +36,14 @@ - Narration over the picture, when the footage has no voice for it, is `` from `raea/speech` (Pocket TTS, on this computer; `voice` picks a Pocket voice or a WAV of one). -- Master the sum with one `` per composition. It brings the whole mix to -14 LUFS - integrated and limits true peaks under the ceiling, which is what the floor's loudness defect asks for. +- raea mixes and masters every render: each line of dialogue (the `voice` bus, or footage on no bus) comes to the same + loudness, a join into dead silence gets the room's tone, and the whole mix comes to -14 LUFS integrated with true + peaks under -1 dBTP, which is what the floor's loudness defect asks for. Don't level lines with `gainDb` or master + the voice outside raea. One `` per composition sets another target. - Put the sounds in the tree in time order. The engine keys a sound's stretch by its place in the tree, so adding a sound in the middle of the list can split the ones after it. -- Balance relative to the voice. The approved pieces, mastered by `` to -14 LUFS, sit like this: +- Balance relative to the voice. The approved pieces, mastered to -14 LUFS, sit like this (each a `gainDb` on top of + raea's level for the voice, or on the sound's own level for the rest): | sound | with a voice | without one (promo, deck, game) | |---|---|---| @@ -110,7 +113,6 @@ ends up shouting over the narrator while another is inaudible. - `loop` on an `