@koda-sl/baker-cli 0.340.0-dev.10990633f → 0.341.0-dev.5221753c2

package/README.md

@@ -32,7 +32,7 @@ export BAKER_GSC_SITE_URL="https://example.com/"
 # Optional: default X Ads account ID (base36)
 export BAKER_X_ADS_ACCOUNT_ID="18ce53xyz"
 
-# Required for `baker actions ...` and `baker scheduled-agents create/update/delete` commands that stage against a chat
+# Required for `baker actions ...` and `baker scheduled-actions create/update/delete` commands that stage against a chat
 export BAKER_CHAT_ID="<chat-id>"
 ```
 
@@ -43,7 +43,7 @@ export BAKER_CHAT_ID="<chat-id>"
 - `BAKER_GA4_PROPERTY_ID` — default GA4 property ID. Used when `--property-id` is not passed. If neither is set and exactly one property is connected, it is auto-selected.
 - `BAKER_GSC_SITE_URL` — default GSC site URL. Used when `--site-url` is not passed. If neither is set and exactly one site is verified, it is auto-selected.
 - `BAKER_X_ADS_ACCOUNT_ID` — default X Ads account ID (base36). Used when `--account-id` is not passed. If neither is set and exactly one X Ads account is connected, it is auto-selected.
-- `BAKER_CHAT_ID` — chat context for staged Work Action commands and staged Scheduled agent create/update/delete. `scheduled-agents run` does not require it. When set, it is also sent as an `x-baker-chat-id` header on every request, so library additions that apply immediately (images, videos, followed brands) are listed in that chat's changes as already applied.
+- `BAKER_CHAT_ID` — chat context for staged Work Action commands and staged Scheduled Action create/update/delete. `scheduled-actions trigger` does not require it. When set, it is also sent as an `x-baker-chat-id` header on every request, so library additions that apply immediately (images, videos, followed brands) are listed in that chat's changes as already applied.
 
 ## Debug logging
 
@@ -689,7 +689,7 @@ Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remo
 
 **Amending a staged op** — `draft amend <ref> (--file patch.json | --patch '<json>')` merges a JSON patch into an already-staged op's payload (objects deep-merge, `null` deletes a key, arrays/scalars replace) and re-validates it in full. Always prefer this over removing and re-staging — it preserves the op's ref (so dependents don't break) and its position in the draft. `draft show <ref>` prints the full staged payload (including warnings/annotations) so you can verify a change looks right before publish.
 
-**Reading an earlier chat's changes** — `draft list` and `draft show` take `--chat <chat-id>` to read another chat in the same company instead of the current one. Every staged-draft family accepts it: `ads google|meta|linkedin draft list|show`, `tag-manager draft list|show`, `actions draft`, `tags draft`, and `scheduled-agents list|get`. A published draft is kept in full, so this returns what that chat actually wrote — every headline, bid and target — plus each op's outcome and error. Use it when asked to redo or reapply earlier work rather than reconstructing copy from a summary. Read-only: staging, `amend`, `remove` and `clear` stay bound to `BAKER_CHAT_ID`, so one chat can never edit another's draft. To re-run only the changes a publish failed to land, use the chat's **Retry** control in the dashboard — it re-sends exactly those and leaves the ones that applied untouched.
+**Reading an earlier chat's changes** — `draft list` and `draft show` take `--chat <chat-id>` to read another chat in the same company instead of the current one. Every staged-draft family accepts it: `ads google|meta|linkedin draft list|show`, `tag-manager draft list|show`, `actions draft`, `tags draft`, and `scheduled-actions list|get`. A published draft is kept in full, so this returns what that chat actually wrote — every headline, bid and target — plus each op's outcome and error. Use it when asked to redo or reapply earlier work rather than reconstructing copy from a summary. Read-only: staging, `amend`, `remove` and `clear` stay bound to `BAKER_CHAT_ID`, so one chat can never edit another's draft. To re-run only the changes a publish failed to land, use the chat's **Retry** control in the dashboard — it re-sends exactly those and leaves the ones that applied untouched.
 
 **Already-satisfied writes aren't staged** — an update or pause/resume whose every field already holds the requested value on the live account is dropped instead of staged: the envelope returns `"staged": false, "noop": true` with a `reason` ("this ad is already Paused on Google Ads"), plus a hint. This is a success, not an error — there is nothing to publish. Only a positively-read live snapshot can trigger it; a failed or empty read always stages. Batch responses list the dropped ops under `skipped`, and `count` reflects what actually entered the draft.
 
@@ -1683,6 +1683,20 @@ baker gsc sitemaps --site-url "https://example.com/"
 
 ---
 
+### Knowledge vault (`baker knowledge`)
+
+Search the workspace's Knowledge vault — the `src/content/` collections declared in `src/collections/*.ts`, plus `src/brand/BRAND.md` — from any folder inside the workspace.
+
+```bash
+baker knowledge search "what objections do price-sensitive customers raise"
+baker knowledge search "best performing hooks" -c campaigns -n 8   # -c repeatable or comma-separated
+baker knowledge search "tarifa hogar" --keyword                    # exact terms only: instant, no network
+baker knowledge status                                             # collections and index coverage
+baker knowledge index                                              # bring the index up to date
+```
+
+`search` returns passages (`path`, `line`, `title`, `collection`, `score` 0–1, `snippet`; `--full` for the whole passage; `--min-score` to cut). It ranks by keyword and by meaning and then reranks, keeping its index in `.cache/knowledge/`. The index updates itself before each search, so edits are searchable at once. Without Baker credentials, or when the service is unreachable, it answers from keywords alone and a hint says so.
+
 ### Competitive Intelligence (`baker research`)
 
 Market and competitor research powered by DataForSEO and AI-powered Google Search grounding. Shows who's competing for keywords, search intent classification, competitor keyword strategies, keyword gaps, landing page performance, and open-ended AI research.
@@ -3261,79 +3275,63 @@ baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --top-n 10 --out
 
 ---
 
-### Scheduled agents (`baker scheduled-agents`)
+### Scheduled Actions (`baker scheduled-actions`)
 
-A Scheduled agent is a **trigger** and a **prompt**. When the trigger fires, a Session opens with that prompt and does the job — there is no Task in between. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `list` and `get` include draft state when `BAKER_CHAT_ID` is set. `run` fires a published item immediately and does not require a chat id.
+Manage company-scoped scheduled recipes that spawn Work Actions later or on a cadence. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `list` and `get` include draft state when `BAKER_CHAT_ID` is set. `trigger` runs immediately on a published scheduled action and does not require a chat id. Use a regular Work Action instead when there is no date or cadence.
 
 ```bash
-baker scheduled-agents triggers                    # every trigger there is
-baker scheduled-agents list
-baker scheduled-agents get <id-or-temp_agent_id>
+baker scheduled-actions list
+baker scheduled-actions get <id-or-temp_sched_id>
 
-baker scheduled-agents create --name "Weekly report" --description "Prepare report" --prompt "Review last week's spend." --cron "0 9 * * MON" --timezone Europe/Madrid
-baker scheduled-agents create --name "Launch reminder" --description "Check launch" --prompt "Check the launch checklist." --run-at "2026-09-01T07:00:00Z" --disabled
-baker scheduled-agents create --name "Chase a new quote" --description "Follow up while it is warm" --prompt "Read the answers and draft the follow-up." --trigger form.submitted --form quote
-baker scheduled-agents create --name "Celebrate the first sale" --description "Once, ever" --prompt "Write the announcement." --trigger event.received --event purchase --occurrences 1
+baker scheduled-actions create --name "Weekly report" --description "Prepare report" --cron "0 9 * * MON" --timezone Europe/Madrid
+baker scheduled-actions create --name "Launch reminder" --description "Check launch" --run-at "2026-09-01T07:00:00Z" --disabled --no-spawn-agent
+baker scheduled-actions create --name "Spend review" --description "Review spend anomalies" --cron "0 9 * * MON" --prompt "Focus on blockers"
 
-baker scheduled-agents update <id-or-temp_agent_id> --enabled false
-baker scheduled-agents update <id-or-temp_agent_id> --run-at "2026-09-02T07:00:00Z" --prompt "Use the launch checklist"
-baker scheduled-agents update <id-or-temp_agent_id> --trigger experiment.ended
-baker scheduled-agents delete <id-or-temp_agent_id>
+baker scheduled-actions update <id-or-temp_sched_id> --enabled false
+baker scheduled-actions update <id-or-temp_sched_id> --run-at "2026-09-02T07:00:00Z" --spawn-agent true --prompt "Use the launch checklist"
+baker scheduled-actions update <id-or-temp_sched_id> --mode publish     # runs go live unreviewed
+baker scheduled-actions update <id-or-temp_sched_id> --mode recommend   # runs advise and change nothing
+baker scheduled-actions delete <id-or-temp_sched_id>
 
-baker scheduled-agents run <id>
+baker scheduled-actions trigger <id>
 
-baker scheduled-agents templates --list                  # every recipe this company can run
-baker scheduled-agents templates --category measurement  # one group only
-baker scheduled-agents create --template baker-ads --name "Weekly ad review" --description "..." --cron "0 8 * * MON"
+baker scheduled-actions templates --list                  # every recipe this company can run
+baker scheduled-actions templates --category measurement  # one group only
+baker scheduled-actions create --template baker-ads --name "Weekly ad review" --description "..." --cron "0 8 * * MON"
 ```
 
-Triggers:
-
-| `--trigger` | Fires when | Narrow it with |
-|---|---|---|
-| *(use `--run-at`)* | Once, at a time you pick | — |
-| *(use `--cron`)* | On a repeating cadence | — |
-| `webhook.received` | Another tool posts to this item's own private address | — |
-| `event.received` | An event arrives from the site or a connected tool | `--event <name>` |
-| `form.submitted` | Somebody sends answers from a Form | `--form <slug>` |
-| `flow.step.submitted` | Somebody gets as far as one step of a Form | `--form <slug> --step <id>` |
-| `experiment.ended` | Somebody ends an A/B test | `--experiment <id>` |
-| `experiment.concluded` | The winner has been moved into the page | `--experiment <id>` |
-| `task.completed` | A Task is closed | `--tag <slug>` |
-| `task.claimed` | An agent picks up a Task | `--tag <slug>` |
-
 Rules:
 
-- `--cron`, `--run-at` and `--trigger` are mutually exclusive — an item has exactly one trigger.
-- `--run-at` must be an ISO UTC timestamp ending in `Z`, and still in the future — a time that has already passed is refused when the op is staged. If a one-off's time passes while the chat is still open, publishing creates it **switched off** with the reason on it rather than dropping it.
-- Leaving a narrowing flag off means "any" — any Form, any event, any test — including ones that do not exist yet.
-- `--occurrences 1` runs only the first time the trigger ever fires; `--occurrences 1,3` the first and the third. Omit it to run every time. It counts firings of this item's trigger, so a firing that `--occurrences` declines is still counted.
-- A signal-triggered item will not start a second run while its last one is still going, and never wakes itself.
-- `--prompt` is the whole job: there is no mode and no `--spawn-agent`. If a run should only advise, the brief says so.
-- Publishing every run's work unreviewed is a standing authorization only the user can grant, on the item in Baker. The API refuses `autoPublish` outright.
-- Draft-created ids use `temp_agent_*`; use them with `get`, `update`, or `delete` before publish.
+- `--cron` and `--run-at` are mutually exclusive.
+- `--run-at` must be an ISO UTC timestamp ending in `Z`, and still in the future — a time that has already passed is refused when the op is staged. If a one-off's time passes while the chat is still open, publishing creates the task **switched off** with the reason on it rather than dropping it, so it is never lost.
+- Draft-created ids use `temp_sched_*`; use them with `get`, `update`, or `delete` before publish.
 - Staged commands require `BAKER_CHAT_ID` to point to an `in_progress` chat.
-- `run` rejects `temp_agent_*` and only accepts published ids. It returns the `chatId` of the Session it opened.
+- `trigger` rejects `temp_sched_*` and only accepts published scheduled-action ids.
 - Company Timezone is the default; `--timezone` is an explicit IANA override.
-- `--template <id>` copies a marketplace recipe's brief onto the item — a copy, not a link, so the owner can read and edit every word, and a later change to the recipe does not reach it. `--prompt` is appended after it. The same recipe can be used more than once.
+- `--mode` sets how far a run goes on its own: `remind` (opens the Task, runs nothing), `recommend` (writes up what it would change, touches nothing), `propose` (does the work, waits to be published — the default), `publish` (does the work and publishes it unreviewed). It applies when the chat is published, on the authority of whoever published it; a chat completed with no person behind it lands a `publish` task on `propose` instead.
+- `--mode` supersedes `--spawn-agent`/`--no-spawn-agent`, which can only reach `remind` and `propose`. Passing both is rejected.
+- Scheduled actions spawn agents by default; create with `--no-spawn-agent` or update with `--spawn-agent false` to disable it.
+- `--prompt` maps to the scheduled action's additional spawned-agent instructions (`agentPrompt`), not a replacement for Baker's automatic spawned Work Action reference.
+- `--prompt` requires a run that does the work: it is rejected alongside `--mode remind`, `--no-spawn-agent` (create) or `--spawn-agent false` (update), since a bypassed agent never reads it.
+- `--template <id>` binds the schedule to a marketplace recipe instead of a prompt you wrote. The row stores the id alone: name, brief and prompt resolve at fire time, so the job improves when the recipe does. `--description` carries what is true of this company. One row per recipe per company; a second `create` for the same id is refused.
 
 #### Marketplace recipes (`templates`)
 
-`templates` lists every recipe a company can build an item from — the ones Baker maintains plus any the company wrote — and is also how one of theirs is written. Recipes we maintain take priority: a company recipe can never use one of our ids, and resolution reads ours first.
+`templates` lists every recipe a company can switch on — the ones Baker maintains plus any the company wrote — and is also how one of theirs is written. Recipes we maintain take priority: a company recipe can never use one of our ids, and resolution reads ours first.
 
 ```bash
-baker scheduled-agents templates --list --drafts        # include theirs not offered yet
+baker scheduled-actions templates --list --drafts        # include theirs not offered yet
 
 # Writing one of theirs, in this order:
-baker scheduled-agents templates --save weekly-posthog-check \
+baker scheduled-actions templates --save weekly-posthog-check \
   --name "Weekly PostHog check" \
   --tagline "What moved in the funnel, from PostHog rather than GA4." \
   --recipe-category measurement --frequency weekly \
   --brief-file ./brief.md
 
-# ...build an item from it with --template, run that item, read what it produced, then:
-baker scheduled-agents templates --publish weekly-posthog-check
-baker scheduled-agents templates --delete weekly-posthog-check
+# ...schedule it with --template, trigger it, read what the run produced, then:
+baker scheduled-actions templates --publish weekly-posthog-check
+baker scheduled-actions templates --delete weekly-posthog-check
 ```
 
 - **Saving does not offer it.** A saved recipe is invisible and cannot be scheduled until `--publish`. The step between the two is running it: nothing enforces that, and it is the only way to know it produces anything worth reading.
@@ -3451,7 +3449,7 @@ baker actions create --name "Build hero" --priority high --tags landing,creative
 # (temp_hero_copy, not hero_copy) and is rejected with a VALIDATION_ERROR otherwise — the prefix is
 # what tells a task staged in this chat apart from a published action id in link/update/complete/draft remove.
 # If the name/description reads as recurring or future-dated (e.g. "weekly", "every Monday", "schedule"),
-# create emits a hint to use `baker scheduled-agents create` instead of a Work Action.
+# create emits a hint to use `baker scheduled-actions create` instead of a Work Action.
 # If it instead names work a surface executes in-chat (a GTM container change, a site tag, an ad-platform
 # write, a page or form edit, or a value only the user has), create emits a do-it-now hint naming that
 # surface — doing the work is the default, an action is the exception. One advisory hint per call: the