From 88c7084c4e44b3d9925b99175d27439341ff6118 Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Thu, 12 Nov 2026 13:12:25 -0800 Subject: [PATCH 1/3] Agents docs: no Director. The workspace has one primary, the harness at its root that takes whatever nothing else was picked for (a connected AI on a model, or one of the person's agents); New chat's menu picks a connected AI's model or an agent; an agent is a provider with more on top, kept in the workspace's folder (agents.feature A1c, A6) --- docs/agents.feature | 45 ++++++++++++++++++++- docs/manual/tutorials/connect-your-agent.md | 30 +++++++++----- docs/manual/tutorials/controllers.md | 4 +- docs/manual/tutorials/index.md | 2 +- docs/manual/tutorials/tour.md | 3 +- 5 files changed, 68 insertions(+), 16 deletions(-) diff --git a/docs/agents.feature b/docs/agents.feature index abb7ba2c..11f49bcf 100644 --- a/docs/agents.feature +++ b/docs/agents.feature @@ -27,6 +27,9 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te 3. Whoever posts an item is its subscriber: what the person sends on it reaches that session, inside raea or out. 4. A session states its own role. One started from a template in raea gets the template's role without asking; one started outside raea says who it is when it posts, and may change it. + 5. There's no Director. The workspace has one primary: the harness that runs at its root (its own chats) and + whatever the person doesn't pick for. It's a provider on a model, or one of the person's agents; making an agent + the primary is how someone gets an orchestrator, and it's still only that choice (A6, Shane 11-12). Background: Given the app is apps/app (raea-feed): src/chat, src/agent, src/model/agents.ts, host/acp, host/feed-items.ts @@ -48,9 +51,24 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te Scenario: A1b. A template is a choice, never a requirement Given a workspace with no agents - Then New chat, the feed's composer and a project's chat all work, each on the workspace's default provider + Then New chat, the feed's composer and a project's chat all work, each on the workspace's primary + + Scenario: A1c. One menu picks the AI, its model or an agent + # Shane 11-12: "when I go to composer and I select a model, I could pick a model provider that I have, only show + # the ones that are connected ... groups with those model providers at the top of the dropdown, and then we + # could scroll down and look at our agents or type to search and select an agent" + # Status 11-12: built (raea-feed primary-agents: src/chat/RunsOn.tsx; e2e "New chat runs on a provider", + # "an agent is a provider on a model"). + When I open what a chat runs on, under New chat's box + Then the AIs signed in on this Mac come first, Kimi first, each a group of its models; one that isn't signed in + or isn't on this Mac isn't offered (Settings → Plugins connects it) + And the person's agents come under them, each with its square mark and what it runs on + And typing searches both, and Enter picks the first match + And the pick is that chat's: the next New chat starts on the primary again Rule: A2. raea ships no agent types + # Status 11-12: the dev page's sample agents (Planner, Builder, Cutter, ...) are authors only too: they keep their + # recorded sessions for the e2e suite, and no list offers them (raea-feed primary-agents, model/data.ts). # Status 11-09: built (raea-feed 601d4ae). No Director or Critic is made; the planner and critique post as raea # (raeaAgent, provider "raea"), tasks for it say @raea and an old brief's @director reads as raea. The built app's # sample world keeps its agents as `by` authors only (model/data.ts sampleAuthors); the dev page keeps them as @@ -139,3 +157,28 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te And the hooks hold inside the raea app too, which runs each ACP agent with its own shell and config And `raea show` names its poster from the harness that started it, found up its parent processes when the harness doesn't mark its shell, so Kimi, OpenCode and the rest post as themselves with an inbox per session + + Rule: A6. One primary, and agents are providers with more on top + # Shane 11-12: "in our docs we say like there's a director and the director owns everything. That's not really + # true. All we have is a primary agent harness that runs in the global root of the workspace ... I could assign an + # agent to be that level, that orchestrator or that like director, but it's really just a primary harness choice + # or model choice." And: "the ability to create an agent that is something beyond calling the model harness ... + # those agents ... are in fact just the model provider with all the same bells and whistles". + # Status 11-12: built (raea-feed primary-agents). The primary is settings.chatOn + chatModel (chat/provider.ts + # primaryOf); Settings → Agents sets it. Agents are kept as agents/.json in the workspace's folder + # (host/agents.ts, POST /host/agents) with launch.model. + + Scenario: A6a. The primary runs the workspace + Given Settings → Agents, whose first row is the primary, Kimi on its own default model until changed + When I pick an AI's model or one of my agents there + Then the workspace's own chats (New chat with no project, the Inbox's composer, the Controllers page's bar) run on + it at the workspace's root, and so does every chat, feed message and task where nothing else is picked or named + And no page calls it a Director: an agent made the primary is an orchestrator only because it's there + + Scenario: A6b. An agent is a provider on a model, with its own name, instructions and tools + When I make an agent in Settings → Agents (New agent) + Then I pick what it runs on (Kimi, Claude, ChatGPT, Gemini, OpenCode, or a command of my own) and, for a provider, + one of its models, beside its name, colour, instructions, tools and approvals + And it's kept in the workspace's folder as agents/.json, so it's there after a restart and travels with the + workspace's repo + And chats on it run its model with its instructions, as a chat on the bare provider would with none diff --git a/docs/manual/tutorials/connect-your-agent.md b/docs/manual/tutorials/connect-your-agent.md index cef41f07..beb7e5ce 100644 --- a/docs/manual/tutorials/connect-your-agent.md +++ b/docs/manual/tutorials/connect-your-agent.md @@ -1,13 +1,13 @@ --- title: "Connect your agent" -summary: "Bring the AI you already pay for over ACP, add agents to your workspace with their own instructions, and start work with the Director." +summary: "Bring the AI you already pay for over ACP, pick the primary that runs your workspace, and make agents of your own when you want them." order: 2 sources: ["apps/app/src/plugins", "apps/app/src/settings/Agents.tsx", "apps/app/src/agent/AgentEditor.tsx", "apps/app/src/acp", "apps/app/src/chat"] tutorial: "connect-your-agent" --- -raea runs the agent you already use. This tutorial connects one, shows where your workspace's agents live, and -introduces the Director, the agent you talk to first. +raea runs the agent you already use. This tutorial connects one, picks the primary that runs your workspace, and +shows how to make agents of your own when you want them. ## How raea uses your agent @@ -29,17 +29,25 @@ If your agent isn't listed, choose Your own agent, and give raea the command tha over standard input and output will work. raea starts it in the project's folder, so it reads and writes the project's files directly. -## Agents in your workspace +## The primary -Now open Settings, then Agents. Each agent here is a role, such as the Director, a Designer or an Animator, and each one -says which AI runs it and whether it's signed in. Press New agent to add another. Give it a name, choose what runs it, -and write its instructions in plain words. Agents belong to the workspace, so every project can call on them. +Now open Settings, then Agents. The first row is the primary: the AI that runs your workspace. It answers in New chat +when no project is picked, takes what you write in the Inbox and on the Controllers page, and starts any work you don't +hand to someone else. Pick any AI you've connected and one of its models, Kimi until you change it. That's all the +primary is. raea doesn't add a director or a cast of agents on top. -## The Director +## Choosing in New chat -Every workspace has a Director. It's the agent you talk to in New chat. It reads the whole workspace, makes projects, -and builds controllers when you ask for them. Write what you want in New chat, pick a project under the box, and the -Director starts the work there. +Under New chat's box, one menu says what the chat runs on. The AIs signed in on this computer come first, each with +its models, and your agents come after them. Type to search. What you pick is for that chat only; the next one starts +on the primary again. + +## Agents of your own + +raea ships no agents. When you want one, press New agent. An agent is one of your AIs with more on top: a name you can +mention with @, the model it runs, instructions in plain words, the tools it may use, and what it may do without +asking. It's kept in your workspace's folder, so it's still there tomorrow, and every project can call on it. You can +even make one the primary, if you want a lead that works your way. ## Agents in a terminal diff --git a/docs/manual/tutorials/controllers.md b/docs/manual/tutorials/controllers.md index b4492d4a..f1644b22 100644 --- a/docs/manual/tutorials/controllers.md +++ b/docs/manual/tutorials/controllers.md @@ -23,8 +23,8 @@ saved at once, for the whole project. ## Make one in plain words -To add a controller, press New controller, and say what you want in plain words. The Director builds it from raea's -field types, and it appears on the page, ready to adjust. +To add a controller, press New controller, and say what you want in plain words. Your workspace's primary builds it +from raea's field types, and it appears on the page, ready to adjust. ## Workflows diff --git a/docs/manual/tutorials/index.md b/docs/manual/tutorials/index.md index 698f1061..061e1330 100644 --- a/docs/manual/tutorials/index.md +++ b/docs/manual/tutorials/index.md @@ -12,7 +12,7 @@ to your agent. Take them in order the first time: each one builds on the one bef ## Start here - [Get started with raea](get-started.md): download the app, sign in on raea.io, link your Mac, and land in your first project. -- [Connect your agent](connect-your-agent.md): bring the AI you already pay for, add agents to your workspace, and meet the Director. +- [Connect your agent](connect-your-agent.md): bring the AI you already pay for, pick the primary that runs your workspace, and make agents of your own. - [A tour of the app](tour.md): what each part of the sidebar is for, from New chat to Settings. ## Make and review diff --git a/docs/manual/tutorials/tour.md b/docs/manual/tutorials/tour.md index 40e23a70..246c90f9 100644 --- a/docs/manual/tutorials/tour.md +++ b/docs/manual/tutorials/tour.md @@ -18,7 +18,8 @@ menu, or make a new one for each client. ## New chat New chat is where work starts. It's one box. Write what you want made, in your own words, and pick a project under the -box. The workspace's Director reads it and starts the work, and the session appears in the sidebar. +box. The workspace's primary, the AI you picked in Settings, reads it and starts the work, and the session appears in +the sidebar. ## Inbox From 6471e1d1ffa4d6b6d5996c39f22e2a75c8283afc Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Thu, 12 Nov 2026 13:49:41 -0800 Subject: [PATCH 2/3] =?UTF-8?q?Agents=20docs:=20each=20AI's=20own=20settin?= =?UTF-8?q?gs=20(agents.feature=20A7).=20Settings=20=E2=86=92=20Agents=20l?= =?UTF-8?q?ists=20the=20AIs=20signed=20in=20on=20this=20Mac,=20each=20with?= =?UTF-8?q?=20what=20its=20ACP=20session=20reports=20it=20can=20be=20set?= =?UTF-8?q?=20to=20(thinking,=20mode,=20its=20own=20switches=20such=20as?= =?UTF-8?q?=20Claude's=20fast=20mode)=20plus=20environment=20and=20extra?= =?UTF-8?q?=20arguments;=20an=20agent=20on=20that=20AI=20shows=20the=20sam?= =?UTF-8?q?e=20settings,=20each=20defaulting=20to=20the=20AI's;=20they=20l?= =?UTF-8?q?ayer=20AI=20default,=20the=20Mac's=20defaults,=20the=20agent's,?= =?UTF-8?q?=20then=20the=20chat's=20model,=20and=20one=20that=20no=20longe?= =?UTF-8?q?r=20applies=20becomes=20a=20notice?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/agents.feature | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/agents.feature b/docs/agents.feature index 11f49bcf..5aa9acd9 100644 --- a/docs/agents.feature +++ b/docs/agents.feature @@ -182,3 +182,38 @@ Feature: Agents in the raea app: chats run on a provider, agents are optional te And it's kept in the workspace's folder as agents/.json, so it's there after a restart and travels with the workspace's repo And chats on it run its model with its instructions, as a chat on the bare provider would with none + + Rule: A7. Each AI's own settings, for the AI and for an agent on it + # Shane 11-12: "acp allows us to adjust provider/harness specific options?" and "selecting a harness for a custom + # agent ... we would need the same settings and options once we select what we pick". + # An ACP session reports its config options (session/new configOptions): each has a category (mode, model, + # thought_level, model_config, or the AI's own) and is a select or a switch. Claude's: mode, model, effort, fast, + # ultracode. Kimi's: model, thinking, mode. raea draws them as reported, so no AI needs code of its own. + # Status 11-12: built (raea-feed primary-agents). Page: agent/AgentOptions.tsx, settings/AIOptions.tsx and the + # agent editor; host: app-prefs providers (POST /host/onboard ai-prefs), host/acp/hub.ts optionsFor, bridge.ts + # useOptions. + + Scenario: A7a. An AI's defaults on this Mac + Given Settings → Agents, whose Your AIs lists every AI signed in on this Mac, each saying what's set for it + When I open an AI's Options + Then I see every setting it reports but its model, grouped as Thinking, Mode and More, each on Default, which names + the AI's own value + And I can give it environment variables (NAME=value) and extra arguments to start with + And what I save is kept on this Mac and reaches every chat on that AI started afterwards: the primary, a chat + picked in New chat, and an agent on it that doesn't set its own + + Scenario: A7b. An agent on an AI has the same settings + When I pick what an agent runs on in its editor + Then the same settings show for that AI, each on Default, which names the value I gave the AI ("Claude's: High") + or else the AI's own + And what I set is the agent's (launch.options, launch.env, launch.extraArgs), and picking another AI starts them + over + And a command of my own has no settings to show; only its environment is kept + + Scenario: A7c. Settings layer, and one that no longer applies says so + Given the AI's own default, then my defaults for the AI, then the agent's settings, then the chat's model + When a session starts + Then each setting is the last of those that sets it, applied with session/set_config_option + And one the AI no longer reports, or a value it refuses, is skipped with a notice in the chat, never a failure + And raea changes no mode for me: Approve everything (Settings → General) already answers the AI's permission asks, + so its own bypass or yolo mode, or a plan-only mode, is on only if I pick it From 87c6c1a7206f71b88a506ad7f5c329a6f552df3e Mon Sep 17 00:00:00 2001 From: shinyobjectz Date: Thu, 12 Nov 2026 18:12:31 -0800 Subject: [PATCH 3/3] The tour says how to consolidate the Inbox or a feed into a summary on its timeline, and that a working agent has a stop button beside it in the Agents list, the Feed's chat and the Inbox (raea-feed PR #1: c43ff66, 8fe9953) --- docs/manual/tutorials/tour.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/manual/tutorials/tour.md b/docs/manual/tutorials/tour.md index 246c90f9..0343406b 100644 --- a/docs/manual/tutorials/tour.md +++ b/docs/manual/tutorials/tour.md @@ -27,6 +27,11 @@ The Inbox gathers everything your agents make, across every project, newest firs cut, a still, a sound, a board or a game. The number beside the Inbox counts what you haven't seen yet. The Inbox is the best place to start your day. +When the Inbox or a feed gets long, fold it up: right-click past its cards, or open its settings, and choose +Consolidate. Everything but your pins becomes one summary on the timeline, which says how many, from when to when, what +kinds, who made them and how many are unread. It opens in place to its cards, a search still finds what's inside, and +Ungroup in its menu puts them back. What comes after shows as ever until you consolidate again. + ## Publish Publish is where finished work goes out, to the accounts you've connected, such as YouTube, LinkedIn or Bluesky. It @@ -41,7 +46,9 @@ you publish to, generation services, and computers of your own. Under Projects, each project is a folder. Open one, and it has three pages. The Feed shows the project's work. The Compositions page shows what each piece is made of. And Controllers holds the project's settings, which every agent -works to. In the Feed, the Agents button lists the project's agents, and what each one is working on. +works to. In the Feed, the Agents button lists the project's agents, and what each one is working on. While an agent +works, a stop button sits beside it, in that list, beside its status in the Feed's chat and on the message it's +answering in the Inbox. Press it to stop that agent. ## Chats and Settings