# Hermes Chat → Idea Briefs (the Idea Bot's daily brief)

**Portal:** Manage · **Nav:** My Assistant → **Idea Briefs** (`/manage/idea-briefs`), the tab shows for super admins ·
**Namespace:** `Src\IdeaBrief` · **Routes:** `manage.idea-briefs.*`, `webhooks.hermes-lab.idea-briefs.*` ·
**Parent:** [Hermes Chat](/docs/modules_handbook/agent-app/hermes-chat/readMe.md)

## What it does

Leg 1 of the growth relay (Shawn, 2026-11-04): the marketing team's video ideas start from one brief a day.

- Every morning the **Idea Bot** on the Hermes lab box reads the news and writes one brief: a market update when there is big
  news, a basic lesson when there is not.
- The brief lands on this page and only its owner hears about it, in their assistant chat.
- Only the owner can see it. They read it, tick the facts they have checked, and then pick who gets it, ask the bot for a new
  version, or reject it. Nobody else sees it until then, other super admins included (Shawn, 2026-11-05).
- People it was sent to get a chat message with a link back here, plus a phone alert if they have the agent app. They can read
  that brief but not decide on it.
- The brief's code (`IB-20261104`) goes into each video's creative id and the ad name or `utm_content`, so a booking can be
  traced back to the idea.
- **Team feedback** on the list page (bookings, what customers said) goes into the bot's next brief.

## How it works

**The bot is outside PETA.** It lives on the box as the `idea-bot` profile; the box runbook's *Idea Bot* section
(`/srv/propertylab-brain/_System/runbook.md`) covers its jobs and how to stop it. Its source is not in this repo.

- It has web search and no other tool, no PETA access and no notes. It reads forum posts and web pages written by strangers,
  so it must hold nothing worth stealing. **Never give that profile PETA tools.**
- A script fetches the fixed sources first (EdgeProp, Google News, Lowyat), so nothing there depends on the AI finding it.
- The script, not the AI, supplies each source's link and the "source status" block.

**Only the bot starts a call,** because the box sits behind its own firewall:

1. `POST /webhooks/hermes-lab/idea-briefs` (`HermesLabIdeaBriefsController::store`) delivers a brief. Signed with the shared
   secret (`HermesLabAdmin::PURPOSE_IDEA`), at most five minutes old. The same code and version again changes nothing, so the
   bot can retry. PETA sends the owner's chat message only the first time.
2. `POST /webhooks/hermes-lab/idea-briefs/pending` is its every-15-minutes check. It returns open change requests, the last
   seven ideas (rejected ones marked, to avoid them) and the latest 20 pieces of feedback.
3. A change request therefore takes up to 15 minutes. The new version arrives through step 1 with the next `version`, and the
   older versions become `STATUS_REPLACED`.

**Before this page is deployed** the endpoint answers 404, and the bot sends the brief to the owner's chat with typed approval
("批准 IB-…，发给 …") instead. That path stays on the box as the fallback.

**Who sees what.** The bot names the owner's profile in every brief. The webhook stores that person as `idea_briefs.owner_id`,
and refuses a brief with an unknown owner (422), since nobody could see it. Both rules live in the code, not in the route:

- **Read:** `IdeaBrief::restrictToViewer`: the owner, and anyone in `idea_brief_recipients`. It covers the list, its counts, one
  brief and its versions. Anyone else gets a 404 or an empty list.
- **Decide:** `IdeaBriefsController::ownedBrief`: only the owner can tick checks, approve, ask for a change, reject or undo.
- **Team feedback** stays open to every super admin. It holds no brief.

**Sending** (`IdeaBriefRepository::approve`) writes the recipient row and the chat message
(`HermesMessageRepository::notice`) in one transaction, under a lock on the brief, so a double click sends nothing twice and a
recorded recipient always has the message. The controller then queues `SendHermesChatPush`. It keeps only people the page offers:

- **Who is offered:** active super admins, since a brief links to this page and only they can reach it.
- **Who can be ticked:** those with a ready, switched-on assistant. The others show as "Has not set up an assistant yet".

**The design lives on the page.** The chat renders Markdown only (`utils/markdown.js`), so it gets a short summary and a link.
`briefText.js` renders the bot's text: `renderMarkdown` escapes everything first, then each `[S3]`/`[W1]` becomes a link to that
source. A ref with no source, or one that is not https, is dropped. `W` refs are links the AI found itself, labelled "AI 搜索到".

## Known gaps

- Super admins only for now. Opening it to a marketing role means a real permission, and widening `people()` to match.
- One owner per brief, so nobody else can send it while the owner is away. Changing the owner means the bot's `IDEA_BOT_OWNER`
  setting for new briefs and `owner_id` for existing ones.
- The Brief ID reaches a booking only if the video and ad carry it. `lead_funnels.utm_content` stores it, but no report
  groups bookings by brief yet.
- iProperty and PropertyGuru block the box (403), so the bot reports that and relies on Google News and web search.

## Related files

**Backend**
- `src/IdeaBrief/IdeaBrief.php`: types, statuses, the two chat messages
- `src/IdeaBrief/IdeaBriefRecipient.php`, `src/IdeaBrief/IdeaBriefFeedback.php`
- `src/IdeaBrief/Repositories/IdeaBriefRepository.php`
- `app/Http/Controllers/Manage/IdeaBriefs/IdeaBriefsController.php`, `app/Http/Requests/Manage/IdeaBriefs/`
- `app/Http/Controllers/Webhooks/HermesLabIdeaBriefsController.php`, `app/Http/Requests/Webhooks/HermesLabIdeaBriefs/`
- `src/Hermes/Services/HermesLabAdmin.php`: `PURPOSE_IDEA`

**Frontend**
- `resources/js/Pages/Manage/IdeaBriefs/Index.vue`, `Show.vue`, `Partials/SendPanel.vue`, `briefText.js`
- `resources/js/Components/MyAssistantTabs.vue`: the tab; `resources/js/Layouts/ManageLayout.vue`: the sidebar's `prefixes`

**Migrations**
- `database/migrations/2026_11_04_220000_create_idea_briefs_tables.php`
- `database/migrations/2026_11_05_004500_add_owner_id_to_idea_briefs_table.php`

**Routes**
- `routes/web.php`: `manage.idea-briefs.*`
- `routes/main.php`: `webhooks.hermes-lab.idea-briefs.*`

**Tests**
- `tests/Feature/IdeaBrief/IdeaBriefsTest.php`, `resources/js/Pages/Manage/IdeaBriefs/briefText.test.js`
