What an embedded block actually is
A container inside someone else's document that renders your markup under that container's rules. It shows the page, more or less, inside their frame. It does not give the page an address of its own, and it does not run under your policy.
What the container takes away
- An address. There is no URL that is just your page — only a location inside a doc.
- Your security policy. Scripts and embeds run under the host's rules, not a CSP you set.
- Access control. Reach is the document's sharing model, not a gate on the page.
- Portability. The page lives inside a product; moving it means extracting it again.
What a link at a URL keeps
Its own address, its own strict CSP, its own gates, and a plain-text form the agent can re-read. The page is a first-class thing you can point at, protect, and move, rather than a guest in a container.
curl -X POST https://read.botook.ai/v1/publish -F file=@index.htmlThe revision problem, again
Update the agent's output and the embedded copy is stale until someone re-pastes it. A
published link updates in place — update_site swaps the bytes, the URL and every
embed of it stay current.
When an embed is genuinely fine
For a small, static fragment that will never change and never needs a boundary — a chart, a snippet — dropping it into a doc is the least effort and perfectly reasonable. The trade only bites when the thing needs an address, a policy, or an update.
The better composition
Publish the page to a URL, then link or embed that URL in the document. Now the doc shows the latest version and the page still owns its behaviour — you get the convenience without giving up the address.
Can I embed a published page inside a document?
Yes — publish it to a URL and embed that URL. The page keeps its policy and updates in place, and the document always shows the current version.
Why does the security policy matter for an embed?
Because inside a container your page runs under the host's rules, not the strict CSP a viewer response sets here. For anything assembled from real data, that difference is the point.