[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75XF7FENF85YGCQ5R56QJM8":3,"skill-same:01M75XF7FENF85YGCQ5R56QJM8":53},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":29,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M75XF7FENF85YGCQ5R56QJM8","project-site-review",null,"Use when working on the site-review widget, `public\u002Flive-review\u002Fwidget.js`, `src\u002FModule\u002FSiteReview\u002F`, its API routes, the dev harness or `e2e\u002Ftests\u002Fsite-review\u002F`.","loupe-ac\u002Floupe","loupe-ac","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F345019842?v=4","01M75XDH3V7GZDHB5M0J04BFTP","Loupe","01M75XDH4EWXVAMQEHFV5TWBMF",2,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fproject-site-review\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: project-site-review\ndescription: \"Use when working on the site-review widget, `public\u002Flive-review\u002Fwidget.js`, `src\u002FModule\u002FSiteReview\u002F`, its API routes, the dev harness or `e2e\u002Ftests\u002Fsite-review\u002F`.\"\n---\n\n# Site review (working on it)\n\nA reviewer opens a widget on any web page, points at an element, and leaves a comment. The comment saves at once as feedback on a board card, and the owner's agent pulls it over MCP. There is no draft and no send step.\n\nThe Board module owns the card side. `POST \u002Fapi\u002Fv1\u002Flive-review-widget\u002Ffeedback` writes the card, the comment and the link in one transaction. `SiteReview` stores the comment and stays card-blind.\n\nTo consume the site-review MCP tools as an agent, see `loupe-site-review`. That job has different hazards.\n\n## The widget is not part of the app's frontend\n\n`public\u002Flive-review\u002Fwidget.js` is a standalone, self-contained script that runs on third-party pages. The app does not build it, bundle it or style it.\n\nDo not apply `project-frontend` to it. Its design-token rules (`@theme`, `@apply`, semantic classes in `app.css`, no arbitrary values) govern the stylesheet of the Symfony app, and they are wrong here. The widget carries its own hex-value palette in the `CHROME` \u002F `LIGHT` \u002F `DARK` maps near the top of the file. It injects that palette into two shadow roots, one for the panel and one for the overlay. Raw hex and literal pixel values are correct here.\n\nInvoke `project-frontend` only for a change in `assets\u002F` or a Twig template.\n\n| Trap | What happens |\n|---|---|\n| Formatting it by hand | `just cs` runs prettier over `public\u002Flive-review\u002F`, and `just lint` checks it. Run `just cs` before you commit. |\n| Serena's edit tools | No language server is configured for JavaScript in this project. `replace_content` and similar tools fail with \"No language servers available\". Use Edit\u002FWrite. Serena reads still work. |\n| `text-overflow` in the overlay | JS sets `display` as an inline style on several overlay nodes, and that beats the stylesheet. `text-overflow: ellipsis` has no effect on the anonymous text item of a flex container. An `inline-flex` label therefore clips mid-word and shows no ellipsis. Check the JS-applied `display` before you debug the CSS. |\n| Absolutely-positioned `display` | The overlay's label is `position: absolute`, so `display` blockifies: `inline-block` computes to `block`, `inline-flex` to `flex`. The computed style does not show what you wrote. |\n| Reading the platform from one source | Playwright's Chromium reports `navigator.userAgentData.platform` as `Windows` while it runs on macOS, and `navigator.platform` as `MacIntel`. The add-anchor modifier of the widget takes either Mac signal, because Ctrl+click on a Mac is a right click. The widget's own `contextmenu` handler then stands the picker down. Every pick after the first then fails, and it looks like a lost click. In a spec, mirror the same expression instead of reading `process.platform`. |\n\n## The status model\n\n```\nPending  →  Addressed  →  (Resolved)\n```\n\n- `Pending`: the reviewer saved it and the agent has not acted. A comment is created in this state. There is no draft.\n- `Addressed`: the agent fixed it (`feedback_mark_addressed`).\n- `Resolved`: a human signed it off, on the card's Feedback tab or from the widget. A card that moves into a terminal column also resolves its feedback. An agent that finishes a card with `card_update` therefore reaches this state too. No tool resolves a comment directly.\n\n`Draft` was removed with the send step. Any reference to it is stale.\n\n`findOnePending()` gates both edit and delete, and it fails with no signal. A wrong predicate makes rehydrate return nothing, and edits and deletes return 404. The widget still renders correctly and appears to forget everything. There is no exception and no log. Test a real edit-and-delete round trip after you touch it.\n\nA comment is editable and deletable only while it is `Pending`. When the agent marks it `Addressed`, the reviewer's in-flight edit returns 404, and the widget says the agent picked it up. The comment leaves the reviewer's list, because the widget lists only `Pending` comments.\n\n## Ownership voters do not constrain agents\n\nAn MCP request authenticates as the project owner. The rule of `CardFeedbackVoter` (`card_feedback.resolve` \u002F `card_feedback.reopen`, in Board) is an ownership check on the card and the comment. Every ownership-based voter therefore returns true for an MCP call by construction.\n\nRouting and firewall config stop an agent from resolving a comment by hand. Authorization does not. No tool calls a resolve route. `OAuthAccessTokenAuthenticator` runs only on the `mcp` and `api` firewalls. A Bearer token thus cannot reach the resolve route of the card page on `main` at all. A card move is the one path: the resolve-on-finish listeners run for a `card_update` move as for any other move.\n\nThe result of an ownership voter is thus no real check on what an agent may do. When you add a tool, do not reason \"`CardFeedbackVoter` will stop it.\"\n\n`App\\Security\\McpBoundProjectVoter` (`site_review.mcp_read` \u002F `site_review.mcp_write`) is the one voter that does constrain an agent. The review and board modules share it, and it reaches the project of a subject through `App\\Security\\ProjectScopedSubject`. It compares the subject's project against the project the *token* is bound to, which is narrower than ownership. A token minted for project A cannot reach project B, even when one user owns both. Every caller-supplied site or comment id that reaches an MCP tool goes through `SiteReviewSubjectResolver`. That resolver asks that voter and nothing else. Resolve the ids of a new tool there, and do not re-derive the scope.\n\n## A comment carries an opaque context, and SiteReview never reads it\n\n`SiteReviewComment::$context` holds whatever the embed's `data-context` attribute said, fed by `SITE_REVIEW_WIDGET_CONTEXT`. It is null on an ordinary deployment. The template renders no attribute when the variable is empty, and the controller turns a blank value into null.\n\nThe column is a plain string and not a relation, on purpose. The value names a row that this module cannot see. `card:\u003Cuuid>` is the first shape, written by a worktree preview, and the Board module resolves it. Do not add a foreign key, and do not parse the value here. A `pr:` or `branch:` prefix must cost no migration and no change to this module.\n\n`AddCommentHandler` dispatches `SiteReviewCommentCreated` inside its transaction, after the comment has an id. That event is the public API of the module, the same contract that `ProjectDeleting` carries. Nothing listens to it today. A listener that persists rows needs no flush of its own. A listener **must never throw**, because anything it raises aborts the comment save it was told about.\n\n## The push subsystem has no producer\n\n`App\\Outbox\\Entity\\OutboxEvent`, the outbox, `DrainOutboxHandler`, the drain scheduler, both outbox pages, `ShowEventsController` and the `agent.push.enabled` flag are all present and tested. Nothing writes an event any more, because the removal of the send step removed the only producer.\n\nThe outbox now lives in the root namespace under `App\\Outbox`, because it takes the events of every producer and not only those of site review. A row carries a `type`, and this module writes `SiteReviewEventType::SUBMITTED`.\n\nThe empty outbox is deliberate, because the push feature is unfinished. Do not wire a trigger without a decision, and see the card on the project board. Expect an outbox that stays empty, a \"not reached your agent yet\" notice that never shows, and a connected bridge CLI that receives nothing.\n\nCounters that read `OutboxEvent` report zero forever. The projects list counts comments instead. `unsentCount` and the outbox notice stay event-sourced on purpose, because zero is *correct* there.\n\n## API surface\n\nEvery widget route sits under `\u002Fapi\u002Fv1\u002Flive-review-widget`, and `WidgetApiPaths` lists that prefix. The old paths (`\u002Fapi\u002Flive-review\u002F...`, `\u002Fapi\u002Fboard\u002Fcards...`, `\u002Fapi\u002Fboard\u002Ffeedback...`) are gone.\n\n| Route | Method | Purpose |\n|---|---|---|\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Freview` | GET | Rehydrate the widget's list (Pending only) |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcomments\u002F{id}` | PATCH | Edit (Pending only) |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcomments\u002F{id}\u002Fresolve` | POST | Resolve (Pending only) |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Ffeedback` | POST | Save a comment, its target card and the link in one request |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Ffeedback\u002F{id}` | DELETE | Delete a pending comment, and the card it created while that card is untouched: still in Backlog, no other comment, its site-review type and note title, empty body, no pull request, document or card link |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcards` | POST | Create a card from the widget |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcards\u002F{cardId}\u002Fstart` | GET | Show where a widget card stands, and the columns the reviewer may move it to |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcards\u002F{cardId}\u002Fstart` | POST | Move a widget card to one of those columns |\n\nThis module holds two more routes that are not widget paths. `\u002Fapi\u002Fv1\u002Fbridge\u002Fprojects` and `\u002Fapi\u002Fv1\u002Fbridge\u002Fevents` serve the loupe CLI. `\u002Fapi\u002Fv1\u002Fbridge\u002Fevents` returns the caller's own user topic and a subscriber JWT for that one topic. `DrainOutboxHandler` publishes each event on its project topic and on the user topic of the project owner. The URL and the JWT thus keep one size, however many projects a user owns. The firewall grants each route by its own rule to `ROLE_API_AGENT`. The `site-review` scope does not carry that role, so a widget sign-in gets a 403 Problem JSON answer with the code `credential_not_allowed`. The routes keep their `ShowEventsController` and `ListSitesController` classes here because their command handlers live here.\n\nThe widget routes under `\u002Fapi\u002Fv1\u002Flive-review-widget` include Board routes on the `site-review` scope. `config\u002Fpackages\u002Fsecurity.yaml` grants the prefix in one `access_control` line, so the grant is visible to anyone who reads that file. `WidgetApiPaths` keeps CORS and the write rate limit on the prefix. Both listeners tested one prefix before, and a listener that tests one prefix exempts every other endpoint the widget reaches, with no signal.\n\nThe widget carries no credential. The embed names a project with `data-project`, and the reviewer signs in through an OAuth pop-up. The grant is bound to that one project, carries the `site-review` scope, and lives in the session storage of the tab. Only the owner of the project can sign in, and the page's origin must be on the project's allowed sites. `PrepareWidgetAuthorizationHandler` holds both checks.\n\nWidget-scoped endpoints reject a token with the `agent` scope, and account-scoped endpoints reject the `site-review` scope. `\u002Fapi\u002Fv1\u002Fbridge\u002Fevents` refuses it outright.\n\n## Accepted: the site-review scope reads, edits and deletes every pending comment\n\nThe owner accepted this exposure. Do not treat it as an open finding.\n\n- Do not re-file it as a card on the project board.\n- Do not report it as a new discovery in an audit.\n- Do not narrow `findOnePending()` or the CORS policy without a maintainer decision.\n\nThe acceptance covers the staging-and-preview-only deployment model and no further. Sign-in is owner-only for now, so the holder is the owner of the project. Expect the acceptance to carry more weight when sign-in widens past the owner.\n\n`references\u002Faccepted-exposure.md` records exactly what is accepted, why it is possible and what bounds it. It also records the attribution half and the deferred per-project origin allowlist. Read it before you touch this area.\n\n## The dev harness\n\n`\u002Fdev\u002Flive-review-harness?email=\u003Cuser>` renders a page with the widget loaded and the project reset. `&keep=1` keeps existing comments across a reload. The harness throws unless the user exists, so seed the user first:\n\n```bash\ncurl -sk -X POST https:\u002F\u002Floupe.dev.localhost\u002Fdev\u002Fregister-and-verify \\\n  --data-urlencode \"fullName=Widget Preview\" \\\n  --data-urlencode \"email=e2e-site-review@example.com\" \\\n  --data-urlencode \"password=E2eSiteReview1!\"\n```\n\n### Driving it in a browser\n\n- Do not pixel-click the launcher. Its width changes with the comment-count badge. A coordinate that hit the crosshair on an empty project misses once a comment exists.\n- A `keydown` on `document` does not toggle pick mode. Click the button inside the shadow root instead:\n\n```js\nconst hosts = [...document.querySelectorAll('*')].filter(e => e.shadowRoot);\nconst pick = hosts.flatMap(h => [...h.shadowRoot.querySelectorAll('button')])\n                  .find(b => b.getAttribute('data-tip') === 'Pick element');\npick.click();\n```\n\nHover states need a real `mousemove` with client coordinates, because the widget picks its target with `document.elementFromPoint`.\n\n## Testing\n\n`e2e\u002Ftests\u002Fsite-review\u002Fwidget.spec.ts` is the real coverage. It asserts the **visibility** of the highlight and not its geometry, so padding and colour changes do not break it. `tests\u002FModule\u002FSiteReview\u002FWidgetFileTest.php` asserts structural facts about the file itself.\n\nThe e2e suite needs no messenger consumer. Every message dispatched during a request that carries `X-Playwright: 1` is handled inline.\n\n### A widget mode change does not settle in one frame\n\nA move into or out of pick, draw or compose mode moves focus, re-renders both shadow roots, and animates the toast into its dock. A test that acts or asserts immediately after the mode change races all three.\n\n`widget.spec.ts` carries the two races that bit. `canvasReadyAt` waits for the toast to stop and for the canvas to be the topmost node before a stroke. The toast crosses the page as it docks, and it swallows the press. The quote offer after draw mode was worse. It came back for about 15ms and then went, so the test passed on a transient until a loaded machine missed the window. That one was a widget defect, and the fix keeps the pick when the widget's own chrome takes focus.\n\nWait on the precondition that the next action needs, never on the mode flag. A flag often flips before the work it starts has finished.\n\nThe same rule shapes a fix in the widget. Read the promise, not the flag, and narrow to the states that deliberately break it. Four attempts at the quote guard failed because they keyed on the mode that wanted the pick kept. That flag is already false when the event lands.\n\nDo not expire an arm by counting frames. Chromium dispatches `selectionchange` in its own task, and a frame often runs before it, even on an idle machine. The first quote fix expired its arm after two frames and lost the pick on every run. `focusKeepingPick()` now arms only when it sees the focus collapse a live selection, and the arm waits for that event. Its arrival is proven in Chromium only. A press on the page drops the arm, so a browser that sends no event cannot leave it up for the reviewer's own collapse.\n\nEvery mode exit that focuses the composer goes through `focusKeepingPick()`. That covers Done and Escape out of draw mode, a first pick, a pick into an open comment, and the end of the add-another hold. `widget.spec.ts` tests each one, plus the dropped arm. A test must wait for the widget to read the collapse, and `afterSelectionRead` does that.\n\nA mode that owns the pointer hides the offer in `renderQuoteButton`. It must never clear the pick in `readSelection`. A `selectionchange` can land at any point during the mode, the drag's own trailing event included, and the exit promises the offer back. `state.target` sat in both lists and caused the second appearance of this race.\n\n## Common mistakes\n\n| Mistake | Reality |\n|---|---|\n| Applying `project-frontend`'s token rules to `widget.js` | It is standalone; raw hex and px are correct there. |\n| Trusting an ownership voter to stop an agent | Ownership voters return true for every MCP call; `App\\Security\\McpBoundProjectVoter` is the one that does not. |\n| Assuming a comment is private until \"sent\" | There is no send step. It is live on save. |\n| Adding a `Draft` branch | The status no longer exists. |\n| Wiring a Mercure trigger to \"fix\" the empty outbox | The missing producer is a decision. Do not treat it as a bug. |\n","# Site review (working on it)\n\nA reviewer opens a widget on any web page, points at an element, and leaves a comment. The comment saves at once as feedback on a board card, and the owner's agent pulls it over MCP. There is no draft and no send step.\n\nThe Board module owns the card side. `POST \u002Fapi\u002Fv1\u002Flive-review-widget\u002Ffeedback` writes the card, the comment and the link in one transaction. `SiteReview` stores the comment and stays card-blind.\n\nTo consume the site-review MCP tools as an agent, see `loupe-site-review`. That job has different hazards.\n\n## The widget is not part of the app's frontend\n\n`public\u002Flive-review\u002Fwidget.js` is a standalone, self-contained script that runs on third-party pages. The app does not build it, bundle it or style it.\n\nDo not apply `project-frontend` to it. Its design-token rules (`@theme`, `@apply`, semantic classes in `app.css`, no arbitrary values) govern the stylesheet of the Symfony app, and they are wrong here. The widget carries its own hex-value palette in the `CHROME` \u002F `LIGHT` \u002F `DARK` maps near the top of the file. It injects that palette into two shadow roots, one for the panel and one for the overlay. Raw hex and literal pixel values are correct here.\n\nInvoke `project-frontend` only for a change in `assets\u002F` or a Twig template.\n\n| Trap | What happens |\n|---|---|\n| Formatting it by hand | `just cs` runs prettier over `public\u002Flive-review\u002F`, and `just lint` checks it. Run `just cs` before you commit. |\n| Serena's edit tools | No language server is configured for JavaScript in this project. `replace_content` and similar tools fail with \"No language servers available\". Use Edit\u002FWrite. Serena reads still work. |\n| `text-overflow` in the overlay | JS sets `display` as an inline style on several overlay nodes, and that beats the stylesheet. `text-overflow: ellipsis` has no effect on the anonymous text item of a flex container. An `inline-flex` label therefore clips mid-word and shows no ellipsis. Check the JS-applied `display` before you debug the CSS. |\n| Absolutely-positioned `display` | The overlay's label is `position: absolute`, so `display` blockifies: `inline-block` computes to `block`, `inline-flex` to `flex`. The computed style does not show what you wrote. |\n| Reading the platform from one source | Playwright's Chromium reports `navigator.userAgentData.platform` as `Windows` while it runs on macOS, and `navigator.platform` as `MacIntel`. The add-anchor modifier of the widget takes either Mac signal, because Ctrl+click on a Mac is a right click. The widget's own `contextmenu` handler then stands the picker down. Every pick after the first then fails, and it looks like a lost click. In a spec, mirror the same expression instead of reading `process.platform`. |\n\n## The status model\n\n```\nPending  →  Addressed  →  (Resolved)\n```\n\n- `Pending`: the reviewer saved it and the agent has not acted. A comment is created in this state. There is no draft.\n- `Addressed`: the agent fixed it (`feedback_mark_addressed`).\n- `Resolved`: a human signed it off, on the card's Feedback tab or from the widget. A card that moves into a terminal column also resolves its feedback. An agent that finishes a card with `card_update` therefore reaches this state too. No tool resolves a comment directly.\n\n`Draft` was removed with the send step. Any reference to it is stale.\n\n`findOnePending()` gates both edit and delete, and it fails with no signal. A wrong predicate makes rehydrate return nothing, and edits and deletes return 404. The widget still renders correctly and appears to forget everything. There is no exception and no log. Test a real edit-and-delete round trip after you touch it.\n\nA comment is editable and deletable only while it is `Pending`. When the agent marks it `Addressed`, the reviewer's in-flight edit returns 404, and the widget says the agent picked it up. The comment leaves the reviewer's list, because the widget lists only `Pending` comments.\n\n## Ownership voters do not constrain agents\n\nAn MCP request authenticates as the project owner. The rule of `CardFeedbackVoter` (`card_feedback.resolve` \u002F `card_feedback.reopen`, in Board) is an ownership check on the card and the comment. Every ownership-based voter therefore returns true for an MCP call by construction.\n\nRouting and firewall config stop an agent from resolving a comment by hand. Authorization does not. No tool calls a resolve route. `OAuthAccessTokenAuthenticator` runs only on the `mcp` and `api` firewalls. A Bearer token thus cannot reach the resolve route of the card page on `main` at all. A card move is the one path: the resolve-on-finish listeners run for a `card_update` move as for any other move.\n\nThe result of an ownership voter is thus no real check on what an agent may do. When you add a tool, do not reason \"`CardFeedbackVoter` will stop it.\"\n\n`App\\Security\\McpBoundProjectVoter` (`site_review.mcp_read` \u002F `site_review.mcp_write`) is the one voter that does constrain an agent. The review and board modules share it, and it reaches the project of a subject through `App\\Security\\ProjectScopedSubject`. It compares the subject's project against the project the *token* is bound to, which is narrower than ownership. A token minted for project A cannot reach project B, even when one user owns both. Every caller-supplied site or comment id that reaches an MCP tool goes through `SiteReviewSubjectResolver`. That resolver asks that voter and nothing else. Resolve the ids of a new tool there, and do not re-derive the scope.\n\n## A comment carries an opaque context, and SiteReview never reads it\n\n`SiteReviewComment::$context` holds whatever the embed's `data-context` attribute said, fed by `SITE_REVIEW_WIDGET_CONTEXT`. It is null on an ordinary deployment. The template renders no attribute when the variable is empty, and the controller turns a blank value into null.\n\nThe column is a plain string and not a relation, on purpose. The value names a row that this module cannot see. `card:\u003Cuuid>` is the first shape, written by a worktree preview, and the Board module resolves it. Do not add a foreign key, and do not parse the value here. A `pr:` or `branch:` prefix must cost no migration and no change to this module.\n\n`AddCommentHandler` dispatches `SiteReviewCommentCreated` inside its transaction, after the comment has an id. That event is the public API of the module, the same contract that `ProjectDeleting` carries. Nothing listens to it today. A listener that persists rows needs no flush of its own. A listener **must never throw**, because anything it raises aborts the comment save it was told about.\n\n## The push subsystem has no producer\n\n`App\\Outbox\\Entity\\OutboxEvent`, the outbox, `DrainOutboxHandler`, the drain scheduler, both outbox pages, `ShowEventsController` and the `agent.push.enabled` flag are all present and tested. Nothing writes an event any more, because the removal of the send step removed the only producer.\n\nThe outbox now lives in the root namespace under `App\\Outbox`, because it takes the events of every producer and not only those of site review. A row carries a `type`, and this module writes `SiteReviewEventType::SUBMITTED`.\n\nThe empty outbox is deliberate, because the push feature is unfinished. Do not wire a trigger without a decision, and see the card on the project board. Expect an outbox that stays empty, a \"not reached your agent yet\" notice that never shows, and a connected bridge CLI that receives nothing.\n\nCounters that read `OutboxEvent` report zero forever. The projects list counts comments instead. `unsentCount` and the outbox notice stay event-sourced on purpose, because zero is *correct* there.\n\n## API surface\n\nEvery widget route sits under `\u002Fapi\u002Fv1\u002Flive-review-widget`, and `WidgetApiPaths` lists that prefix. The old paths (`\u002Fapi\u002Flive-review\u002F...`, `\u002Fapi\u002Fboard\u002Fcards...`, `\u002Fapi\u002Fboard\u002Ffeedback...`) are gone.\n\n| Route | Method | Purpose |\n|---|---|---|\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Freview` | GET | Rehydrate the widget's list (Pending only) |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcomments\u002F{id}` | PATCH | Edit (Pending only) |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcomments\u002F{id}\u002Fresolve` | POST | Resolve (Pending only) |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Ffeedback` | POST | Save a comment, its target card and the link in one request |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Ffeedback\u002F{id}` | DELETE | Delete a pending comment, and the card it created while that card is untouched: still in Backlog, no other comment, its site-review type and note title, empty body, no pull request, document or card link |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcards` | POST | Create a card from the widget |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcards\u002F{cardId}\u002Fstart` | GET | Show where a widget card stands, and the columns the reviewer may move it to |\n| `\u002Fapi\u002Fv1\u002Flive-review-widget\u002Fcards\u002F{cardId}\u002Fstart` | POST | Move a widget card to one of those columns |\n\nThis module holds two more routes that are not widget paths. `\u002Fapi\u002Fv1\u002Fbridge\u002Fprojects` and `\u002Fapi\u002Fv1\u002Fbridge\u002Fevents` serve the loupe CLI. `\u002Fapi\u002Fv1\u002Fbridge\u002Fevents` returns the caller's own user topic and a subscriber JWT for that one topic. `DrainOutboxHandler` publishes each event on its project topic and on the user topic of the project owner. The URL and the JWT thus keep one size, however many projects a user owns. The firewall grants each route by its own rule to `ROLE_API_AGENT`. The `site-review` scope does not carry that role, so a widget sign-in gets a 403 Problem JSON answer with the code `credential_not_allowed`. The routes keep their `ShowEventsController` and `ListSitesController` classes here because their command handlers live here.\n\nThe widget routes under `\u002Fapi\u002Fv1\u002Flive-review-widget` include Board routes on the `site-review` scope. `config\u002Fpackages\u002Fsecurity.yaml` grants the prefix in one `access_control` line, so the grant is visible to anyone who reads that file. `WidgetApiPaths` keeps CORS and the write rate limit on the prefix. Both listeners tested one prefix before, and a listener that tests one prefix exempts every other endpoint the widget reaches, with no signal.\n\nThe widget carries no credential. The embed names a project with `data-project`, and the reviewer signs in through an OAuth pop-up. The grant is bound to that one project, carries the `site-review` scope, and lives in the session storage of the tab. Only the owner of the project can sign in, and the page's origin must be on the project's allowed sites. `PrepareWidgetAuthorizationHandler` holds both checks.\n\nWidget-scoped endpoints reject a token with the `agent` scope, and account-scoped endpoints reject the `site-review` scope. `\u002Fapi\u002Fv1\u002Fbridge\u002Fevents` refuses it outright.\n\n## Accepted: the site-review scope reads, edits and deletes every pending comment\n\nThe owner accepted this exposure. Do not treat it as an open finding.\n\n- Do not re-file it as a card on the project board.\n- Do not report it as a new discovery in an audit.\n- Do not narrow `findOnePending()` or the CORS policy without a maintainer decision.\n\nThe acceptance covers the staging-and-preview-only deployment model and no further. Sign-in is owner-only for now, so the holder is the owner of the project. Expect the acceptance to carry more weight when sign-in widens past the owner.\n\n`references\u002Faccepted-exposure.md` records exactly what is accepted, why it is possible and what bounds it. It also records the attribution half and the deferred per-project origin allowlist. Read it before you touch this area.\n\n## The dev harness\n\n`\u002Fdev\u002Flive-review-harness?email=\u003Cuser>` renders a page with the widget loaded and the project reset. `&keep=1` keeps existing comments across a reload. The harness throws unless the user exists, so seed the user first:\n\n```bash\ncurl -sk -X POST https:\u002F\u002Floupe.dev.localhost\u002Fdev\u002Fregister-and-verify \\\n  --data-urlencode \"fullName=Widget Preview\" \\\n  --data-urlencode \"email=e2e-site-review@example.com\" \\\n  --data-urlencode \"password=E2eSiteReview1!\"\n```\n\n### Driving it in a browser\n\n- Do not pixel-click the launcher. Its width changes with the comment-count badge. A coordinate that hit the crosshair on an empty project misses once a comment exists.\n- A `keydown` on `document` does not toggle pick mode. Click the button inside the shadow root instead:\n\n```js\nconst hosts = [...document.querySelectorAll('*')].filter(e => e.shadowRoot);\nconst pick = hosts.flatMap(h => [...h.shadowRoot.querySelectorAll('button')])\n                  .find(b => b.getAttribute('data-tip') === 'Pick element');\npick.click();\n```\n\nHover states need a real `mousemove` with client coordinates, because the widget picks its target with `document.elementFromPoint`.\n\n## Testing\n\n`e2e\u002Ftests\u002Fsite-review\u002Fwidget.spec.ts` is the real coverage. It asserts the **visibility** of the highlight and not its geometry, so padding and colour changes do not break it. `tests\u002FModule\u002FSiteReview\u002FWidgetFileTest.php` asserts structural facts about the file itself.\n\nThe e2e suite needs no messenger consumer. Every message dispatched during a request that carries `X-Playwright: 1` is handled inline.\n\n### A widget mode change does not settle in one frame\n\nA move into or out of pick, draw or compose mode moves focus, re-renders both shadow roots, and animates the toast into its dock. A test that acts or asserts immediately after the mode change races all three.\n\n`widget.spec.ts` carries the two races that bit. `canvasReadyAt` waits for the toast to stop and for the canvas to be the topmost node before a stroke. The toast crosses the page as it docks, and it swallows the press. The quote offer after draw mode was worse. It came back for about 15ms and then went, so the test passed on a transient until a loaded machine missed the window. That one was a widget defect, and the fix keeps the pick when the widget's own chrome takes focus.\n\nWait on the precondition that the next action needs, never on the mode flag. A flag often flips before the work it starts has finished.\n\nThe same rule shapes a fix in the widget. Read the promise, not the flag, and narrow to the states that deliberately break it. Four attempts at the quote guard failed because they keyed on the mode that wanted the pick kept. That flag is already false when the event lands.\n\nDo not expire an arm by counting frames. Chromium dispatches `selectionchange` in its own task, and a frame often runs before it, even on an idle machine. The first quote fix expired its arm after two frames and lost the pick on every run. `focusKeepingPick()` now arms only when it sees the focus collapse a live selection, and the arm waits for that event. Its arrival is proven in Chromium only. A press on the page drops the arm, so a browser that sends no event cannot leave it up for the reviewer's own collapse.\n\nEvery mode exit that focuses the composer goes through `focusKeepingPick()`. That covers Done and Escape out of draw mode, a first pick, a pick into an open comment, and the end of the add-another hold. `widget.spec.ts` tests each one, plus the dropped arm. A test must wait for the widget to read the collapse, and `afterSelectionRead` does that.\n\nA mode that owns the pointer hides the offer in `renderQuoteButton`. It must never clear the pick in `readSelection`. A `selectionchange` can land at any point during the mode, the drag's own trailing event included, and the exit promises the offer back. `state.target` sat in both lists and caused the second appearance of this race.\n\n## Common mistakes\n\n| Mistake | Reality |\n|---|---|\n| Applying `project-frontend`'s token rules to `widget.js` | It is standalone; raw hex and px are correct there. |\n| Trusting an ownership voter to stop an agent | Ownership voters return true for every MCP call; `App\\Security\\McpBoundProjectVoter` is the one that does not. |\n| Assuming a comment is private until \"sent\" | There is no send step. It is live on save. |\n| Adding a `Draft` branch | The status no longer exists. |\n| Wiring a Mercure trigger to \"fix\" the empty outbox | The missing producer is a decision. Do not treat it as a bug. |\n",{"name":5,"description":7},"main","b0ae29efd5410c4e5bf9a6ed6aed4b6c1d82e55a",".agents\u002Fskills\u002Fproject-site-review",0,"https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe","https:\u002F\u002Floupe.ac\u002F","https:\u002F\u002Fgithub.com\u002Floupe-ac","The control plane for your agent loops.","2026-11-15 04:50:14",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add loupe-ac\u002Floupe --skill project-site-review",{"tool":39,"command":40},"bunx","bunx skills add loupe-ac\u002Floupe --skill project-site-review",{"tool":42,"command":43},"pnpm","pnpm dlx skills add loupe-ac\u002Floupe --skill project-site-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fproject-site-review\u002FSKILL.md",true,[47],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"references\u002Faccepted-exposure.md","REFERENCE","参考文档",6335,"https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fproject-site-review\u002Freferences\u002Faccepted-exposure.md",[54,61,68,75,82,89],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M75XHSK6MYZ0BH7PJHP378QV","loupe-workers","Use when reading worker runs or bridges through the loupe MCP, stopping, resuming or holding workers, cancelling a bridge command, or recovering workers after a usage limit or network outage.","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002Fplugins\u002Floupe\u002Fskills\u002Floupe-workers\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M75XHPW77P75PPWY8Z7Q9XMZ","loupe-site-review","Use when acting on live-review feedback through the loupe MCP: reading the feedback of a card or project, fixing it, or marking it addressed.","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002Fplugins\u002Floupe\u002Fskills\u002Floupe-site-review\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M75XHK6EZP2FZRQ1B4PS4CGH","loupe-inbox","Use when an agent needs a decision, answer or review from the project owner through the loupe MCP, hands a question or to-do to a person, resumes after an ask closed, or needs its session id.","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002Fplugins\u002Floupe\u002Fskills\u002Floupe-inbox\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M75XHDN9XG71R4T248BZ540A","loupe-documents","Use when writing or revising a document for the Loupe app through the loupe MCP, such as a plan, spec, RFC, audit report or retrospective.","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002Fplugins\u002Floupe\u002Fskills\u002Floupe-documents\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M75XHBERM2SWJ7SJ1EB5M4SB","loupe-discovery","Use when a bridge runs a discovery run of a Loupe project, when a prompt names loupe-discovery, or when writing a readiness report.","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002Fplugins\u002Floupe\u002Fskills\u002Floupe-discovery\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M75XH7X2KCFWPVMQJJAMPYJN","loupe-board","Use when working a Loupe project board through the loupe MCP: reading or writing a card, moving a card, changing the columns, or linking a document or a pull request to a card.","https:\u002F\u002Fgithub.com\u002Floupe-ac\u002Floupe\u002Fblob\u002Fmain\u002Fplugins\u002Floupe\u002Fskills\u002Floupe-board\u002FSKILL.md",[],[]]