[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-posthog-validating-and-publishing-canvases":3,"mdc--kqbpgo-key":48,"related-repo-posthog-validating-and-publishing-canvases":792,"related-org-posthog-validating-and-publishing-canvases":895},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":11,"stars":22,"repoUrl":23,"updatedAt":24,"license":25,"forks":26,"topics":27,"repo":43,"sourceUrl":46,"mdContent":47},"validating-and-publishing-canvases","validate and publish canvas projects","Validate and publish a canvas source project safely: the source-project shape, declared capabilities, reading the current version pointer, iterating on validation diagnostics, guarded publishing with expected_current_version_id, waiting out the queued build, and recovering from a 409 version_conflict or a 429 capacity limit without overwriting concurrent work. Use whenever a canvas edit is ready to save, a canvas publish or build returns diagnostics or a conflict, or a task needs to understand canvas version history.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},"posthog","PostHog","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fposthog.png",[12,16,19],{"name":13,"slug":14,"type":15},"Validation","validation","tag",{"name":17,"slug":18,"type":15},"Deployment","deployment",{"name":20,"slug":21,"type":15},"Engineering","engineering",35568,"https:\u002F\u002Fgithub.com\u002FPostHog\u002Fposthog","2026-08-06T06:09:19.027607",null,2977,[28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"ab-testing","ai-analytics","analytics","cdp","data-warehouse","experiments","feature-flags","javascript","product-analytics","python","react","session-replay","surveys","typescript","web-analytics",{"repoUrl":23,"stars":22,"forks":26,"topics":44,"description":45},[28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"🦔 PostHog is an all-in-one developer platform for building successful products. We offer product analytics, web analytics, session replay, error tracking, feature flags, experimentation, surveys, data warehouse, a CDP, and an AI product assistant to help debug your code, ship features faster, and keep all your usage and customer data in one stack.","https:\u002F\u002Fgithub.com\u002FPostHog\u002Fposthog\u002Ftree\u002FHEAD\u002Fproducts\u002Fcanvas\u002Fskills\u002Fvalidating-and-publishing-canvases","---\nname: validating-and-publishing-canvases\ndescription: >\n  Validate and publish a canvas source project safely: the source-project shape, declared\n  capabilities, reading the current version pointer, iterating on validation diagnostics, guarded\n  publishing with expected_current_version_id, waiting out the queued build, and recovering from a\n  409 version_conflict or a 429 capacity limit without overwriting concurrent work. Use whenever a\n  canvas edit is ready to save, a canvas publish or build returns diagnostics or a conflict, or a\n  task needs to understand canvas version history.\n---\n\n# Validating and publishing canvases\n\nA canvas's source lives in PostHog, versioned per publish. Publishing is guarded: every edit is\nbased on a specific version, and the server refuses to overwrite newer work. Every publish queues\na server-side build, and the canvas renders the last successful build.\n\n## The source project\n\n`canvas-source-retrieve` returns:\n\n- `project` — `schemaVersion` (1), `files` (path → content), `entryHtml` (`\"index.html\"`),\n  `dependencies` (exact platform-pinned versions), `canvasSdkVersion`, `capabilities`.\n- `current_version_id` — the version your edits are based on. Keep it; the publish needs it.\n  It is `null` for a canvas that has never been published — pass that `null` on the first publish.\n\nKeep `index.html` and `dependencies` exactly as returned. You may add relative source files and\nadmitted assets to the project. Use `?worker` for a self-contained module worker and represent\nbinary assets as base64 entries in `assets`; new npm dependencies or dependency-version drift fail\nvalidation.\n\n## Declare capabilities\n\nThe host enforces `project.capabilities` at runtime, so an undeclared `ph` call builds fine and\nthen dies in the rendered canvas. Declare:\n\n- `capabilities.posthog.insights` — every insight short id the canvas passes to `ph.loadInsight`.\n- `capabilities.posthog.captureEvents` — every event name it passes to `ph.capture`.\n- `capabilities.posthog.inlineQueries: true` — when it calls `ph.query` at all.\n\nValidation rejects undeclared literal calls (`capability_missing_*` diagnostics) so you can fix\nthem before publishing; dynamic ids it can only warn about, so keep the declarations complete.\n\n## Validate until clean\n\n`canvas-validate-create` is side-effect free; call it as often as needed.\nDiagnostics carry `severity`, a stable `code`, a `message`, and (for file-specific problems)\n`path` and `line`:\n\n- `error` diagnostics block publishing — fix all of them. Common ones: `import_not_allowed`\n  (bare imports are limited to react, react-dom, @posthog\u002Fquill, recharts, lucide-react, and dayjs),\n  `forbidden_dynamic_import` \u002F `forbidden_require` \u002F `forbidden_inline_script`,\n  `invalid_path`, `capability_missing_insight` \u002F `capability_missing_capture_event` \u002F\n  `capability_missing_inline_queries`,\n  `dependency_not_admitted` \u002F `dependency_version_mismatch`, and path\u002Fsize violations.\n- `warning` diagnostics don't block, but heed them: `network_fetch` \u002F `network_xhr` mean the code\n  reaches for the network directly — the sandbox will block it at runtime; use the `ph` bridge.\n\n## Publish guarded\n\nTwo ways to save, both guarded:\n\n- **Whole project** — `canvas-publish-create` with the complete `project`.\n- **Per-file edits** — `canvas-edit-create` with `operations` (each sets a\n  file's complete content, or deletes it with `content: null`). Prefer this for small changes to a\n  large project; the guard is mandatory here because a diff's meaning depends on its base.\n\nFor a whole-project publish with `canvas-publish-create`:\n\n- Always pass `expected_current_version_id` — the `current_version_id` you read (or explicit\n  `null` on a first publish). Unguarded publishes can silently clobber concurrent edits.\n- Include a short `prompt` describing the change; it becomes the version-history entry's label.\n- Pass `name` only to rename the canvas (e.g. a first build of an untitled canvas).\n- Publish once per requested change. If the user asks for another edit afterwards, re-read the\n  source (the head may have moved) and publish again — don't batch unrelated changes into one\n  version, and don't publish work-in-progress after every micro-edit.\n- A 429 means the team's build capacity is temporarily exhausted. Wait ~30 seconds and retry the\n  same publish; nothing was saved.\n\nThe response returns the new `current_version_id`.\n\n## After publishing: wait for the build\n\nA publish queues a server-side build of the version. **The canvas does not update until the build\nis ready, and nobody else is watching the result — you own it.** Poll `canvas-builds-retrieve`\nevery few seconds (up to ~2 minutes) until the build you queued is terminal:\n\n- `queued`\u002F`building` — in progress; poll again shortly.\n- `ready` — the canvas's `published_build_id` advances to this build (unless a newer publish\n  superseded it first). The task's canvas work is done.\n- `failed` — read the build's error diagnostics, fix the project, and publish again. A failed\n  build never replaces the last good one, so the canvas keeps rendering the previous version —\n  finishing the task here would leave the user with a stale canvas and a silent failure.\n\n## Recovering from 409 version_conflict\n\nA 409 means the canvas moved past your base — a concurrent publish or a revert. The response\nincludes the live `current_version_id`. Never retry unguarded to force your version through:\n\n1. Re-read the source with `canvas-source-retrieve`.\n2. Re-apply your edits to the fresh source (the new head may contain someone else's changes —\n   preserve them).\n3. Publish again with the new `current_version_id`.\n\n## Version history semantics\n\nEach publish appends a full source version and moves the head pointer; users can revert to older\nversions in the app (which republishes and rebuilds them). The guard matters because basing your\npublish on the version you actually read is what keeps a user's revert, another agent's publish,\nand your edit from silently erasing each other.\n",{"data":49,"body":50},{"name":4,"description":6},{"type":51,"children":52},"root",[53,61,67,74,86,184,220,226,247,305,318,324,373,495,501,506,566,577,643,654,660,680,732,738,750,781,787],{"type":54,"tag":55,"props":56,"children":57},"element","h1",{"id":4},[58],{"type":59,"value":60},"text","Validating and publishing canvases",{"type":54,"tag":62,"props":63,"children":64},"p",{},[65],{"type":59,"value":66},"A canvas's source lives in PostHog, versioned per publish. Publishing is guarded: every edit is\nbased on a specific version, and the server refuses to overwrite newer work. Every publish queues\na server-side build, and the canvas renders the last successful build.",{"type":54,"tag":68,"props":69,"children":71},"h2",{"id":70},"the-source-project",[72],{"type":59,"value":73},"The source project",{"type":54,"tag":62,"props":75,"children":76},{},[77,84],{"type":54,"tag":78,"props":79,"children":81},"code",{"className":80},[],[82],{"type":59,"value":83},"canvas-source-retrieve",{"type":59,"value":85}," returns:",{"type":54,"tag":87,"props":88,"children":89},"ul",{},[90,158],{"type":54,"tag":91,"props":92,"children":93},"li",{},[94,100,102,108,110,116,118,124,126,132,134,140,142,148,150,156],{"type":54,"tag":78,"props":95,"children":97},{"className":96},[],[98],{"type":59,"value":99},"project",{"type":59,"value":101}," — ",{"type":54,"tag":78,"props":103,"children":105},{"className":104},[],[106],{"type":59,"value":107},"schemaVersion",{"type":59,"value":109}," (1), ",{"type":54,"tag":78,"props":111,"children":113},{"className":112},[],[114],{"type":59,"value":115},"files",{"type":59,"value":117}," (path → content), ",{"type":54,"tag":78,"props":119,"children":121},{"className":120},[],[122],{"type":59,"value":123},"entryHtml",{"type":59,"value":125}," (",{"type":54,"tag":78,"props":127,"children":129},{"className":128},[],[130],{"type":59,"value":131},"\"index.html\"",{"type":59,"value":133},"),\n",{"type":54,"tag":78,"props":135,"children":137},{"className":136},[],[138],{"type":59,"value":139},"dependencies",{"type":59,"value":141}," (exact platform-pinned versions), ",{"type":54,"tag":78,"props":143,"children":145},{"className":144},[],[146],{"type":59,"value":147},"canvasSdkVersion",{"type":59,"value":149},", ",{"type":54,"tag":78,"props":151,"children":153},{"className":152},[],[154],{"type":59,"value":155},"capabilities",{"type":59,"value":157},".",{"type":54,"tag":91,"props":159,"children":160},{},[161,167,169,175,177,182],{"type":54,"tag":78,"props":162,"children":164},{"className":163},[],[165],{"type":59,"value":166},"current_version_id",{"type":59,"value":168}," — the version your edits are based on. Keep it; the publish needs it.\nIt is ",{"type":54,"tag":78,"props":170,"children":172},{"className":171},[],[173],{"type":59,"value":174},"null",{"type":59,"value":176}," for a canvas that has never been published — pass that ",{"type":54,"tag":78,"props":178,"children":180},{"className":179},[],[181],{"type":59,"value":174},{"type":59,"value":183}," on the first publish.",{"type":54,"tag":62,"props":185,"children":186},{},[187,189,195,197,202,204,210,212,218],{"type":59,"value":188},"Keep ",{"type":54,"tag":78,"props":190,"children":192},{"className":191},[],[193],{"type":59,"value":194},"index.html",{"type":59,"value":196}," and ",{"type":54,"tag":78,"props":198,"children":200},{"className":199},[],[201],{"type":59,"value":139},{"type":59,"value":203}," exactly as returned. You may add relative source files and\nadmitted assets to the project. Use ",{"type":54,"tag":78,"props":205,"children":207},{"className":206},[],[208],{"type":59,"value":209},"?worker",{"type":59,"value":211}," for a self-contained module worker and represent\nbinary assets as base64 entries in ",{"type":54,"tag":78,"props":213,"children":215},{"className":214},[],[216],{"type":59,"value":217},"assets",{"type":59,"value":219},"; new npm dependencies or dependency-version drift fail\nvalidation.",{"type":54,"tag":68,"props":221,"children":223},{"id":222},"declare-capabilities",[224],{"type":59,"value":225},"Declare capabilities",{"type":54,"tag":62,"props":227,"children":228},{},[229,231,237,239,245],{"type":59,"value":230},"The host enforces ",{"type":54,"tag":78,"props":232,"children":234},{"className":233},[],[235],{"type":59,"value":236},"project.capabilities",{"type":59,"value":238}," at runtime, so an undeclared ",{"type":54,"tag":78,"props":240,"children":242},{"className":241},[],[243],{"type":59,"value":244},"ph",{"type":59,"value":246}," call builds fine and\nthen dies in the rendered canvas. Declare:",{"type":54,"tag":87,"props":248,"children":249},{},[250,268,286],{"type":54,"tag":91,"props":251,"children":252},{},[253,259,261,267],{"type":54,"tag":78,"props":254,"children":256},{"className":255},[],[257],{"type":59,"value":258},"capabilities.posthog.insights",{"type":59,"value":260}," — every insight short id the canvas passes to ",{"type":54,"tag":78,"props":262,"children":264},{"className":263},[],[265],{"type":59,"value":266},"ph.loadInsight",{"type":59,"value":157},{"type":54,"tag":91,"props":269,"children":270},{},[271,277,279,285],{"type":54,"tag":78,"props":272,"children":274},{"className":273},[],[275],{"type":59,"value":276},"capabilities.posthog.captureEvents",{"type":59,"value":278}," — every event name it passes to ",{"type":54,"tag":78,"props":280,"children":282},{"className":281},[],[283],{"type":59,"value":284},"ph.capture",{"type":59,"value":157},{"type":54,"tag":91,"props":287,"children":288},{},[289,295,297,303],{"type":54,"tag":78,"props":290,"children":292},{"className":291},[],[293],{"type":59,"value":294},"capabilities.posthog.inlineQueries: true",{"type":59,"value":296}," — when it calls ",{"type":54,"tag":78,"props":298,"children":300},{"className":299},[],[301],{"type":59,"value":302},"ph.query",{"type":59,"value":304}," at all.",{"type":54,"tag":62,"props":306,"children":307},{},[308,310,316],{"type":59,"value":309},"Validation rejects undeclared literal calls (",{"type":54,"tag":78,"props":311,"children":313},{"className":312},[],[314],{"type":59,"value":315},"capability_missing_*",{"type":59,"value":317}," diagnostics) so you can fix\nthem before publishing; dynamic ids it can only warn about, so keep the declarations complete.",{"type":54,"tag":68,"props":319,"children":321},{"id":320},"validate-until-clean",[322],{"type":59,"value":323},"Validate until clean",{"type":54,"tag":62,"props":325,"children":326},{},[327,333,335,341,343,348,350,356,358,364,365,371],{"type":54,"tag":78,"props":328,"children":330},{"className":329},[],[331],{"type":59,"value":332},"canvas-validate-create",{"type":59,"value":334}," is side-effect free; call it as often as needed.\nDiagnostics carry ",{"type":54,"tag":78,"props":336,"children":338},{"className":337},[],[339],{"type":59,"value":340},"severity",{"type":59,"value":342},", a stable ",{"type":54,"tag":78,"props":344,"children":346},{"className":345},[],[347],{"type":59,"value":78},{"type":59,"value":349},", a ",{"type":54,"tag":78,"props":351,"children":353},{"className":352},[],[354],{"type":59,"value":355},"message",{"type":59,"value":357},", and (for file-specific problems)\n",{"type":54,"tag":78,"props":359,"children":361},{"className":360},[],[362],{"type":59,"value":363},"path",{"type":59,"value":196},{"type":54,"tag":78,"props":366,"children":368},{"className":367},[],[369],{"type":59,"value":370},"line",{"type":59,"value":372},":",{"type":54,"tag":87,"props":374,"children":375},{},[376,462],{"type":54,"tag":91,"props":377,"children":378},{},[379,385,387,393,395,401,403,409,410,416,418,424,425,431,432,438,440,446,447,453,454,460],{"type":54,"tag":78,"props":380,"children":382},{"className":381},[],[383],{"type":59,"value":384},"error",{"type":59,"value":386}," diagnostics block publishing — fix all of them. Common ones: ",{"type":54,"tag":78,"props":388,"children":390},{"className":389},[],[391],{"type":59,"value":392},"import_not_allowed",{"type":59,"value":394},"\n(bare imports are limited to react, react-dom, @posthog\u002Fquill, recharts, lucide-react, and dayjs),\n",{"type":54,"tag":78,"props":396,"children":398},{"className":397},[],[399],{"type":59,"value":400},"forbidden_dynamic_import",{"type":59,"value":402}," \u002F ",{"type":54,"tag":78,"props":404,"children":406},{"className":405},[],[407],{"type":59,"value":408},"forbidden_require",{"type":59,"value":402},{"type":54,"tag":78,"props":411,"children":413},{"className":412},[],[414],{"type":59,"value":415},"forbidden_inline_script",{"type":59,"value":417},",\n",{"type":54,"tag":78,"props":419,"children":421},{"className":420},[],[422],{"type":59,"value":423},"invalid_path",{"type":59,"value":149},{"type":54,"tag":78,"props":426,"children":428},{"className":427},[],[429],{"type":59,"value":430},"capability_missing_insight",{"type":59,"value":402},{"type":54,"tag":78,"props":433,"children":435},{"className":434},[],[436],{"type":59,"value":437},"capability_missing_capture_event",{"type":59,"value":439}," \u002F\n",{"type":54,"tag":78,"props":441,"children":443},{"className":442},[],[444],{"type":59,"value":445},"capability_missing_inline_queries",{"type":59,"value":417},{"type":54,"tag":78,"props":448,"children":450},{"className":449},[],[451],{"type":59,"value":452},"dependency_not_admitted",{"type":59,"value":402},{"type":54,"tag":78,"props":455,"children":457},{"className":456},[],[458],{"type":59,"value":459},"dependency_version_mismatch",{"type":59,"value":461},", and path\u002Fsize violations.",{"type":54,"tag":91,"props":463,"children":464},{},[465,471,473,479,480,486,488,493],{"type":54,"tag":78,"props":466,"children":468},{"className":467},[],[469],{"type":59,"value":470},"warning",{"type":59,"value":472}," diagnostics don't block, but heed them: ",{"type":54,"tag":78,"props":474,"children":476},{"className":475},[],[477],{"type":59,"value":478},"network_fetch",{"type":59,"value":402},{"type":54,"tag":78,"props":481,"children":483},{"className":482},[],[484],{"type":59,"value":485},"network_xhr",{"type":59,"value":487}," mean the code\nreaches for the network directly — the sandbox will block it at runtime; use the ",{"type":54,"tag":78,"props":489,"children":491},{"className":490},[],[492],{"type":59,"value":244},{"type":59,"value":494}," bridge.",{"type":54,"tag":68,"props":496,"children":498},{"id":497},"publish-guarded",[499],{"type":59,"value":500},"Publish guarded",{"type":54,"tag":62,"props":502,"children":503},{},[504],{"type":59,"value":505},"Two ways to save, both guarded:",{"type":54,"tag":87,"props":507,"children":508},{},[509,533],{"type":54,"tag":91,"props":510,"children":511},{},[512,518,519,525,527,532],{"type":54,"tag":513,"props":514,"children":515},"strong",{},[516],{"type":59,"value":517},"Whole project",{"type":59,"value":101},{"type":54,"tag":78,"props":520,"children":522},{"className":521},[],[523],{"type":59,"value":524},"canvas-publish-create",{"type":59,"value":526}," with the complete ",{"type":54,"tag":78,"props":528,"children":530},{"className":529},[],[531],{"type":59,"value":99},{"type":59,"value":157},{"type":54,"tag":91,"props":534,"children":535},{},[536,541,542,548,550,556,558,564],{"type":54,"tag":513,"props":537,"children":538},{},[539],{"type":59,"value":540},"Per-file edits",{"type":59,"value":101},{"type":54,"tag":78,"props":543,"children":545},{"className":544},[],[546],{"type":59,"value":547},"canvas-edit-create",{"type":59,"value":549}," with ",{"type":54,"tag":78,"props":551,"children":553},{"className":552},[],[554],{"type":59,"value":555},"operations",{"type":59,"value":557}," (each sets a\nfile's complete content, or deletes it with ",{"type":54,"tag":78,"props":559,"children":561},{"className":560},[],[562],{"type":59,"value":563},"content: null",{"type":59,"value":565},"). Prefer this for small changes to a\nlarge project; the guard is mandatory here because a diff's meaning depends on its base.",{"type":54,"tag":62,"props":567,"children":568},{},[569,571,576],{"type":59,"value":570},"For a whole-project publish with ",{"type":54,"tag":78,"props":572,"children":574},{"className":573},[],[575],{"type":59,"value":524},{"type":59,"value":372},{"type":54,"tag":87,"props":578,"children":579},{},[580,607,620,633,638],{"type":54,"tag":91,"props":581,"children":582},{},[583,585,591,593,598,600,605],{"type":59,"value":584},"Always pass ",{"type":54,"tag":78,"props":586,"children":588},{"className":587},[],[589],{"type":59,"value":590},"expected_current_version_id",{"type":59,"value":592}," — the ",{"type":54,"tag":78,"props":594,"children":596},{"className":595},[],[597],{"type":59,"value":166},{"type":59,"value":599}," you read (or explicit\n",{"type":54,"tag":78,"props":601,"children":603},{"className":602},[],[604],{"type":59,"value":174},{"type":59,"value":606}," on a first publish). Unguarded publishes can silently clobber concurrent edits.",{"type":54,"tag":91,"props":608,"children":609},{},[610,612,618],{"type":59,"value":611},"Include a short ",{"type":54,"tag":78,"props":613,"children":615},{"className":614},[],[616],{"type":59,"value":617},"prompt",{"type":59,"value":619}," describing the change; it becomes the version-history entry's label.",{"type":54,"tag":91,"props":621,"children":622},{},[623,625,631],{"type":59,"value":624},"Pass ",{"type":54,"tag":78,"props":626,"children":628},{"className":627},[],[629],{"type":59,"value":630},"name",{"type":59,"value":632}," only to rename the canvas (e.g. a first build of an untitled canvas).",{"type":54,"tag":91,"props":634,"children":635},{},[636],{"type":59,"value":637},"Publish once per requested change. If the user asks for another edit afterwards, re-read the\nsource (the head may have moved) and publish again — don't batch unrelated changes into one\nversion, and don't publish work-in-progress after every micro-edit.",{"type":54,"tag":91,"props":639,"children":640},{},[641],{"type":59,"value":642},"A 429 means the team's build capacity is temporarily exhausted. Wait ~30 seconds and retry the\nsame publish; nothing was saved.",{"type":54,"tag":62,"props":644,"children":645},{},[646,648,653],{"type":59,"value":647},"The response returns the new ",{"type":54,"tag":78,"props":649,"children":651},{"className":650},[],[652],{"type":59,"value":166},{"type":59,"value":157},{"type":54,"tag":68,"props":655,"children":657},{"id":656},"after-publishing-wait-for-the-build",[658],{"type":59,"value":659},"After publishing: wait for the build",{"type":54,"tag":62,"props":661,"children":662},{},[663,665,670,672,678],{"type":59,"value":664},"A publish queues a server-side build of the version. ",{"type":54,"tag":513,"props":666,"children":667},{},[668],{"type":59,"value":669},"The canvas does not update until the build\nis ready, and nobody else is watching the result — you own it.",{"type":59,"value":671}," Poll ",{"type":54,"tag":78,"props":673,"children":675},{"className":674},[],[676],{"type":59,"value":677},"canvas-builds-retrieve",{"type":59,"value":679},"\nevery few seconds (up to ~2 minutes) until the build you queued is terminal:",{"type":54,"tag":87,"props":681,"children":682},{},[683,702,721],{"type":54,"tag":91,"props":684,"children":685},{},[686,692,694,700],{"type":54,"tag":78,"props":687,"children":689},{"className":688},[],[690],{"type":59,"value":691},"queued",{"type":59,"value":693},"\u002F",{"type":54,"tag":78,"props":695,"children":697},{"className":696},[],[698],{"type":59,"value":699},"building",{"type":59,"value":701}," — in progress; poll again shortly.",{"type":54,"tag":91,"props":703,"children":704},{},[705,711,713,719],{"type":54,"tag":78,"props":706,"children":708},{"className":707},[],[709],{"type":59,"value":710},"ready",{"type":59,"value":712}," — the canvas's ",{"type":54,"tag":78,"props":714,"children":716},{"className":715},[],[717],{"type":59,"value":718},"published_build_id",{"type":59,"value":720}," advances to this build (unless a newer publish\nsuperseded it first). The task's canvas work is done.",{"type":54,"tag":91,"props":722,"children":723},{},[724,730],{"type":54,"tag":78,"props":725,"children":727},{"className":726},[],[728],{"type":59,"value":729},"failed",{"type":59,"value":731}," — read the build's error diagnostics, fix the project, and publish again. A failed\nbuild never replaces the last good one, so the canvas keeps rendering the previous version —\nfinishing the task here would leave the user with a stale canvas and a silent failure.",{"type":54,"tag":68,"props":733,"children":735},{"id":734},"recovering-from-409-version_conflict",[736],{"type":59,"value":737},"Recovering from 409 version_conflict",{"type":54,"tag":62,"props":739,"children":740},{},[741,743,748],{"type":59,"value":742},"A 409 means the canvas moved past your base — a concurrent publish or a revert. The response\nincludes the live ",{"type":54,"tag":78,"props":744,"children":746},{"className":745},[],[747],{"type":59,"value":166},{"type":59,"value":749},". Never retry unguarded to force your version through:",{"type":54,"tag":751,"props":752,"children":753},"ol",{},[754,765,770],{"type":54,"tag":91,"props":755,"children":756},{},[757,759,764],{"type":59,"value":758},"Re-read the source with ",{"type":54,"tag":78,"props":760,"children":762},{"className":761},[],[763],{"type":59,"value":83},{"type":59,"value":157},{"type":54,"tag":91,"props":766,"children":767},{},[768],{"type":59,"value":769},"Re-apply your edits to the fresh source (the new head may contain someone else's changes —\npreserve them).",{"type":54,"tag":91,"props":771,"children":772},{},[773,775,780],{"type":59,"value":774},"Publish again with the new ",{"type":54,"tag":78,"props":776,"children":778},{"className":777},[],[779],{"type":59,"value":166},{"type":59,"value":157},{"type":54,"tag":68,"props":782,"children":784},{"id":783},"version-history-semantics",[785],{"type":59,"value":786},"Version history semantics",{"type":54,"tag":62,"props":788,"children":789},{},[790],{"type":59,"value":791},"Each publish appends a full source version and moves the head pointer; users can revert to older\nversions in the app (which republishes and rebuilds them). The guard matters because basing your\npublish on the version you actually read is what keeps a user's revert, another agent's publish,\nand your edit from silently erasing each other.",{"items":793,"total":894},[794,810,822,834,847,862,877],{"slug":795,"name":795,"fn":796,"description":797,"org":798,"tags":799,"stars":22,"repoUrl":23,"updatedAt":809},"analyzing-expensive-users","analyze expensive users in AI observability","Analyze the most expensive users in AI observability and explain why they cost so much. Use when the user asks about top spenders, expensive users, per-user LLM cost, user-level cost drivers, or patterns behind high AI observability spend.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[800,802,805,808],{"name":801,"slug":30,"type":15},"Analytics",{"name":803,"slug":804,"type":15},"Cost Optimization","cost-optimization",{"name":806,"slug":807,"type":15},"Observability","observability",{"name":9,"slug":8,"type":15},"2026-07-28T05:34:11.117757",{"slug":811,"name":811,"fn":812,"description":813,"org":814,"tags":815,"stars":22,"repoUrl":23,"updatedAt":821},"auditing-endpoints","audit PostHog project endpoints","Audit every endpoint in a PostHog project for staleness, failed materialisations, and unused materialised versions. Use when the user asks \"what endpoints can I clean up?\", \"are any of my endpoints broken?\", \"which materialised versions are still being called?\", or wants a one-shot cleanup pass over the Endpoints product. Produces a prioritised report grouped by issue type, with recommended actions but does not modify anything without explicit confirmation.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[816,817,820],{"name":801,"slug":30,"type":15},{"name":818,"slug":819,"type":15},"Audit","audit",{"name":9,"slug":8,"type":15},"2026-06-08T08:08:33.693989",{"slug":823,"name":823,"fn":824,"description":825,"org":826,"tags":827,"stars":22,"repoUrl":23,"updatedAt":833},"auditing-warehouse-source-health","audit PostHog data warehouse source health","Audit the health of a PostHog project's data warehouse sources and syncs — find every broken or degraded source connection, sync schema, and webhook channel. Use when the user asks \"why are my imports failing?\", \"what's broken with my sources?\", \"why is my warehouse data stale?\", or wants a one-shot triage of source\u002Fsync health before deciding where to dig in. Produces a prioritized report grouped by severity, with recommended next steps. For materialized-view health use `auditing-warehouse-view-health`; for a single failing sync use `diagnosing-failed-warehouse-syncs`.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[828,829,831,832],{"name":818,"slug":819,"type":15},{"name":830,"slug":32,"type":15},"Data Warehouse",{"name":806,"slug":807,"type":15},{"name":9,"slug":8,"type":15},"2026-06-18T08:22:57.67984",{"slug":835,"name":835,"fn":836,"description":837,"org":838,"tags":839,"stars":22,"repoUrl":23,"updatedAt":846},"auditing-warehouse-view-health","audit PostHog materialized view health","Audit the health of a PostHog project's materialized views (saved queries) — find every failed materialization and flag unused or stale materialized views that cost storage and compute. Use when the user asks \"which of my views are broken?\", \"why is this materialized view failing?\", \"are any of my views wasting compute?\", or wants a one-shot triage of view health. For source\u002Fsync health use `auditing-warehouse-source-health`.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[840,841,842,845],{"name":818,"slug":819,"type":15},{"name":830,"slug":32,"type":15},{"name":843,"slug":844,"type":15},"Performance","performance",{"name":9,"slug":8,"type":15},"2026-06-18T08:25:10.936787",{"slug":848,"name":848,"fn":849,"description":850,"org":851,"tags":852,"stars":22,"repoUrl":23,"updatedAt":861},"authoring-error-tracking-alerts","author PostHog error tracking alerts","Author error tracking alerts that fire when an issue is created, reopened, or starts spiking. Use when the user asks to set up error notifications, route exceptions to Slack\u002Fwebhook\u002FLinear, or evaluate which error events are worth alerting on. Covers trigger-event selection, integration choice, dedup against existing alerts, and shipping with the canonical message body shape.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[853,856,859,860],{"name":854,"slug":855,"type":15},"Alerting","alerting",{"name":857,"slug":858,"type":15},"Debugging","debugging",{"name":806,"slug":807,"type":15},{"name":9,"slug":8,"type":15},"2026-06-18T08:24:40.318583",{"slug":863,"name":863,"fn":864,"description":865,"org":866,"tags":867,"stars":22,"repoUrl":23,"updatedAt":876},"authoring-log-alerts","author log alerts in PostHog","Author useful, low-noise log alerts on services in a PostHog project. Use when the user asks to set up alerts for their logs, suggest alerts they should add, or evaluate whether a service is worth monitoring. Covers service triage, baseline characterisation, threshold drafting, back-testing via simulate, and shipping with a notification destination.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[868,869,872,873,875],{"name":801,"slug":30,"type":15},{"name":870,"slug":871,"type":15},"Monitoring","monitoring",{"name":806,"slug":807,"type":15},{"name":874,"slug":555,"type":15},"Operations",{"name":9,"slug":8,"type":15},"2026-07-18T05:10:54.430898",{"slug":878,"name":878,"fn":879,"description":880,"org":881,"tags":882,"stars":22,"repoUrl":23,"updatedAt":893},"building-canvases","create and edit PostHog canvases","Create or edit a PostHog canvas — a sandboxed browser application (data board, document, form, small tool, graphics experiment) stored in PostHog and rendered by the desktop\u002Fweb app. Use when a task asks to build, generate, update, or fix a canvas, or when a canvas id is given as the publish target. Covers resolving or creating the target canvas, choosing an implementation approach (React + Quill vs plain HTML\u002Fbrowser APIs), the read → edit → validate → publish → build loop, and which companion canvas skills to load for the details.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[883,886,889,890],{"name":884,"slug":885,"type":15},"Automation","automation",{"name":887,"slug":888,"type":15},"Design","design",{"name":9,"slug":8,"type":15},{"name":891,"slug":892,"type":15},"Prototyping","prototyping","2026-08-06T06:09:29.946969",74,{"items":896,"total":1022},[897,904,910,917,924,931,939,946,964,980,995,1007],{"slug":795,"name":795,"fn":796,"description":797,"org":898,"tags":899,"stars":22,"repoUrl":23,"updatedAt":809},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[900,901,902,903],{"name":801,"slug":30,"type":15},{"name":803,"slug":804,"type":15},{"name":806,"slug":807,"type":15},{"name":9,"slug":8,"type":15},{"slug":811,"name":811,"fn":812,"description":813,"org":905,"tags":906,"stars":22,"repoUrl":23,"updatedAt":821},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[907,908,909],{"name":801,"slug":30,"type":15},{"name":818,"slug":819,"type":15},{"name":9,"slug":8,"type":15},{"slug":823,"name":823,"fn":824,"description":825,"org":911,"tags":912,"stars":22,"repoUrl":23,"updatedAt":833},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[913,914,915,916],{"name":818,"slug":819,"type":15},{"name":830,"slug":32,"type":15},{"name":806,"slug":807,"type":15},{"name":9,"slug":8,"type":15},{"slug":835,"name":835,"fn":836,"description":837,"org":918,"tags":919,"stars":22,"repoUrl":23,"updatedAt":846},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[920,921,922,923],{"name":818,"slug":819,"type":15},{"name":830,"slug":32,"type":15},{"name":843,"slug":844,"type":15},{"name":9,"slug":8,"type":15},{"slug":848,"name":848,"fn":849,"description":850,"org":925,"tags":926,"stars":22,"repoUrl":23,"updatedAt":861},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[927,928,929,930],{"name":854,"slug":855,"type":15},{"name":857,"slug":858,"type":15},{"name":806,"slug":807,"type":15},{"name":9,"slug":8,"type":15},{"slug":863,"name":863,"fn":864,"description":865,"org":932,"tags":933,"stars":22,"repoUrl":23,"updatedAt":876},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[934,935,936,937,938],{"name":801,"slug":30,"type":15},{"name":870,"slug":871,"type":15},{"name":806,"slug":807,"type":15},{"name":874,"slug":555,"type":15},{"name":9,"slug":8,"type":15},{"slug":878,"name":878,"fn":879,"description":880,"org":940,"tags":941,"stars":22,"repoUrl":23,"updatedAt":893},{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[942,943,944,945],{"name":884,"slug":885,"type":15},{"name":887,"slug":888,"type":15},{"name":9,"slug":8,"type":15},{"name":891,"slug":892,"type":15},{"slug":947,"name":947,"fn":948,"description":949,"org":950,"tags":951,"stars":22,"repoUrl":23,"updatedAt":963},"building-html-canvases","author HTML and CSS PostHog canvases","Author a PostHog canvas with semantic HTML, CSS, and direct browser APIs — documents, articles, generative graphics, 2D canvas and WebGL experiences, and focused experiments where React components add no useful structure. Use after building-canvases has routed a canvas request to a plain-HTML\u002Fbrowser-API implementation. Covers the thin component wrapper the current runtime requires, styling and theming without Quill, drawing surfaces, and animation\u002Fcleanup patterns.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[952,955,956,959,962],{"name":953,"slug":954,"type":15},"CSS","css",{"name":887,"slug":888,"type":15},{"name":957,"slug":958,"type":15},"Graphics","graphics",{"name":960,"slug":961,"type":15},"HTML","html",{"name":9,"slug":8,"type":15},"2026-08-06T06:09:30.313848",{"slug":965,"name":965,"fn":966,"description":967,"org":968,"tags":969,"stars":22,"repoUrl":23,"updatedAt":979},"building-react-quill-canvases","build React and Quill canvases","Author the React + Quill implementation of a PostHog canvas: the single-component contract, the allowed imports, Quill (PostHog's design system) component and composition rules, theme-aware design tokens, loading skeletons, and the in-canvas date picker. Use after building-canvases has routed a canvas request to a React implementation — dashboards, data boards, forms, tools, or any canvas that should look native to PostHog.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[970,971,974,976],{"name":887,"slug":888,"type":15},{"name":972,"slug":973,"type":15},"Frontend","frontend",{"name":975,"slug":38,"type":15},"React",{"name":977,"slug":978,"type":15},"UI Components","ui-components","2026-08-06T06:09:18.633724",{"slug":981,"name":981,"fn":982,"description":983,"org":984,"tags":985,"stars":22,"repoUrl":23,"updatedAt":994},"building-workflows","build and edit PostHog workflows","Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action\u002Fedge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or debug a workflow, campaign, broadcast, drip sequence, or event-triggered automation in the workflows product.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[986,987,990,991],{"name":884,"slug":885,"type":15},{"name":988,"slug":989,"type":15},"MCP","mcp",{"name":9,"slug":8,"type":15},{"name":992,"slug":993,"type":15},"Workflow Automation","workflow-automation","2026-08-06T05:36:26.504811",{"slug":996,"name":996,"fn":997,"description":998,"org":999,"tags":1000,"stars":22,"repoUrl":23,"updatedAt":1006},"check-posthog-loading","inspect PostHog SDK loading across URLs","Inspect how the PostHog JavaScript SDK is loaded across a list of URLs. Use to confirm consistent installation across pages, find pages missing the snippet, detect mismatched API keys or hosts between pages, and verify the load method (head snippet vs deferred vs array.js).\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1001,1002,1003,1004,1005],{"name":801,"slug":30,"type":15},{"name":857,"slug":858,"type":15},{"name":972,"slug":973,"type":15},{"name":806,"slug":807,"type":15},{"name":9,"slug":8,"type":15},"2026-05-07T05:56:19.828048",{"slug":1008,"name":1008,"fn":1009,"description":1010,"org":1011,"tags":1012,"stars":22,"repoUrl":23,"updatedAt":1021},"consuming-endpoints-from-client-code","integrate PostHog endpoints into client applications","Wire a PostHog endpoint into a client app or SDK. Covers fetching the OpenAPI spec, generating a typed client with openapi-generator or @hey-api\u002Fopenapi-ts, sending the right auth header, shaping the variables payload (HogQL code_name vs insight breakdown property), handling rate-limit and materialised-endpoint error responses. Use when the user says \"how do I call my endpoint\", \"generate a client for this\", or \"what auth header do I use\".\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1013,1016,1017,1018],{"name":1014,"slug":1015,"type":15},"API Development","api-development",{"name":972,"slug":973,"type":15},{"name":9,"slug":8,"type":15},{"name":1019,"slug":1020,"type":15},"SDK","sdk","2026-06-08T08:08:34.929454",243]