diff --git a/docs/features/agent.md b/docs/features/agent.md
index cc3c90be2..d06e95b2a 100644
--- a/docs/features/agent.md
+++ b/docs/features/agent.md
@@ -96,7 +96,8 @@ src/admin/pages/site/agent/
 ├── pageContext.ts          — editor adapter: reads active page + store scalars, calls `buildSiteAgentSnapshot`
 ├── executor.ts             — browser-side dispatcher: validates + runs write tools; auto-navigates canvas to node's owning document before each write
 ├── cssTools.ts             — site_apply_css parser + exact-selector merge/replace/delete runners
-├── documentTools.ts        — list/read/open document helpers for pages, templates, and visual components
+├── documentTools.ts        — list/read/open document helpers for pages, templates, and visual components, plus active-document node lookup
+├── htmlTools.ts            — site_insert_html / site_replace_node_html runners and the stripped / head-only import notices (split from executor.ts)
 ├── tokenRunners.ts         — site_set_color_tokens / site_set_font_tokens / site_set_type_scale / site_set_spacing_scale runners (split from executor.ts)
 ├── renderEvidence.ts       — captureAgentRenderSnapshot (site_render_snapshot tool)
 ├── storeRef.ts             — setAgentStoreApi / getAgentStoreApi (avoids store ↔ executor cycle)
@@ -580,6 +581,7 @@ Drivers that support explicit prompt-cache controls (Anthropic) apply `cache_con
 - **Design system first.** Establish or reuse tokens before/while building (`site_set_color_tokens`, `site_set_type_scale`, `site_set_spacing_scale`, `site_set_font_tokens`), then reference them in CSS (`var(--<slug>)`, `var(--text-l)`, `var(--space-m)`, `var(--<font-var>)`) instead of raw hex/px/font-family. The dynamic suffix's `Tokens —` line shows what already exists; `(none …)` means no design system yet.
 - Structure as HTML (`site_insert_html` / `site_replace_node_html`); style with CSS in the same payload — a `<style>` block and/or `class=` attributes referencing the design tokens. The importer classifies selectors, so the agent never hand-builds classes at insert time.
 - `<style>` blocks inside imported HTML are parsed: class-bearing selectors become Selectors-panel classes while preserving complex selector text, class-free selectors (`a:hover`) become ambient rules, and supported `@keyframes` publish as raw keyframes CSS. `style=` attributes land on the node's inline styles. These are applied — not stripped.
+- What the importer does drop comes back as `warnings` on the tool result: `<script>` and `on*` handlers (write a code asset instead), and `<link>` / `<meta>` / `<title>` head elements, which the site generates from its settings. A payload made only of those is rejected with an error naming them, so a bare `<link rel="icon">` is never a silent no-op.
 - CSS-only edits use an explicit `site_apply_css` operation: merge for additive patches, remove-properties for stale declarations, replace only with the selector's complete desired CSS, and delete for whole exact rules. Read the document first before destructive operations; grouped and ungrouped selectors are different identities.
 - One `site_insert_html` call per logical section (nav, hero, pricing, footer = 4–6 calls); smaller chunks recover better if one fails.
 - Per-breakpoint variation: `@media` queries — in the `<style>` block of an insert or inside `site_apply_css` — with min/max-width queries that line up with the breakpoint widths in the dynamic suffix. Never invent ids like `"mobile"` or `"desktop"`.
diff --git a/docs/features/html-import.md b/docs/features/html-import.md
index 7cb7bf493..07ffc50b2 100644
--- a/docs/features/html-import.md
+++ b/docs/features/html-import.md
@@ -8,7 +8,7 @@ The module has two consumers: the paste-HTML UI and the AI agent's `insertHtml`
 
 ## TL;DR
 
-- Single entry point: `importHtml(source)` → `{ nodes, rootIds, body?, stripped, styleCss }`.
+- Single entry point: `importHtml(source)` → `{ nodes, rootIds, body?, stripped, headOnly, styleCss }`.
 - Pipeline: `parseHtml` → `harvestInlineStyles` + `collectStyleCss` → `stripUnsafe` → `walkAndMap`.
 - Mapping is rule-driven (`HTML_TO_MODULE_RULES`). The catch-all `*` rule guarantees every element produces a node — nothing falls through.
 - Every produced node is a real `PageNode`: selectable, draggable, deletable, and re-styleable in the canvas.
@@ -58,7 +58,7 @@ importHtml(source: string)
   4. walkAndMap(doc, inlineStyles)— maps doc.body element children to PageNodes,
                                     attaching each harvested inline bag to its
                                     node's `inlineStyles`. Returns { nodes, rootIds }
-→ { nodes, rootIds, body?, stripped, styleCss }   (ImportResult)
+→ { nodes, rootIds, body?, stripped, headOnly, styleCss }   (ImportResult)
 ```
 
 ### Return type
@@ -78,6 +78,10 @@ interface ImportResult {
   }
   /** Counts of constructs removed by stripUnsafe (scripts, inline handlers). */
   stripped: StripReport
+  /** Tag names the parser placed in <head> (link, meta, title, base, …), which the
+   *  walker never sees. Deduplicated, document order. A bare `<link rel="icon">` at
+   *  the top of a payload lands here in every browser. */
+  headOnly: string[]
   /** Raw concatenated CSS from <style> blocks. Empty when the source had none. */
   styleCss: string
 }
@@ -142,10 +146,11 @@ Callers splice the fragment into the page tree via `insertImportedNodes(parentId
 | `<style>` elements | CSS harvested into `result.styleCss` (then parsed into registry rules); the element is removed |
 | `style="…"` attributes | Declarations harvested onto `node.inlineStyles`; the attribute is removed |
 | HTML comments and processing instructions | Stripped silently — no count |
+| `<link>`, `<meta>`, `<title>`, `<base>` and anything else the parser puts in `<head>` | Never walked (the walker maps `doc.body`); reported by tag name as `headOnly` |
 
 The AI agent should not use stripped constructs for behavior. If an edit needs JavaScript, it writes a real runtime script with `write_code_asset({ type: "script", ... })` and verifies targeting with `inspect_code_runtime` instead of embedding `<script>` or `onclick` in an HTML import. Module scripts import npm packages with bare specifiers and declare them in the same `write_code_asset` call's `dependencies` map.
 
-After insert, `ImportHtmlModal` builds a toast body from the added-selector count plus the non-zero stripped counts, e.g. `"3 CSS selectors, stripped 2 <script>"`. If nothing notable happened, the toast shows only the node count.
+Both consumers tell the author what was dropped. The agent tools (`site_insert_html`, `site_replace_node_html`) return the stripped counts and the head-only tags as sentences in `warnings` next to the importer's own reference warnings, and fold the same sentences into the error when nothing was importable, so a bare `<link rel="icon">` is rejected as "Ignored `<link>`: these belong in the document `<head>`…" rather than a bare "no importable elements". `ImportHtmlModal` builds its toast body from the added-selector count plus the same notices, e.g. `"3 CSS selectors, stripped 2 <script>, ignored <link> from <head>"`. If nothing notable happened, the toast shows only the node count.
 
 **Inline `style="…"` → `node.inlineStyles`.** Before `stripUnsafe` removes a `style` attribute, `harvestInlineStyles` (`inlineStyle.ts`) reads the element's parsed CSSOM declaration and copies **every** declaration into a camelCase bag, dropping only property names rejected by `isEmittableProperty` (the publisher's security denylist — the same gate `cssToStyleRules` uses). A `url(…)` background is canonicalised to `url('payload')` form so the Super Import asset rewriter and the editor's `BackgroundImageControl` recognise it. The bag is attached to the produced node as `node.inlineStyles` — the editor's first-class per-node `style=""` layer — which the publisher emits verbatim and the user edits via the Properties panel's inline-style mode. In Super Import any `url(…)` is uploaded to the media library and rewritten to its media URL.
 
diff --git a/server/ai/tools/site/writeTools.ts b/server/ai/tools/site/writeTools.ts
index 465445cda..7a3ccb0dd 100644
--- a/server/ai/tools/site/writeTools.ts
+++ b/server/ai/tools/site/writeTools.ts
@@ -85,7 +85,7 @@ const insertHtmlTool: AiTool = {
   execution: 'browser',
   requiredCapabilities: SITE_STRUCTURE_CAPS,
   description:
-    'Insert semantic HTML as a subtree of editable nodes under an existing parent. Write structure as HTML (<section>, <h1>, <a>, <button>, <img>, <ul>, ...) and style it with CSS in the same call: put a <style> block in the HTML and/or class= attributes. Custom importer markers: <instatic-loop data-source-id="…" ...> creates a real Loop node (call site_list_loop_sources first for source/table ids and {currentEntry.*} tokens; never place the loop inside a <table>, <tbody> or <tr> — HTML parsing moves it out of the table and leaves its rows behind, publishing one blank row. Wrap the whole <table> in the loop, or use a list); <instatic-outlet data-tag="div"> creates a neutral template content outlet. On PAGE routes the outlet element is not rendered at all — the page content is spliced in at its position — so wrap the outlet in <main> yourself if pages should have a main landmark. data-tag only takes effect on ENTRY routes, where the outlet stays and wraps the entry body (use data-custom-tag for a safe custom element). The importer parses every rule — a bare `.foo {}` selector becomes a reusable Selectors-panel class bound to class="foo"; any other selector (`.hero a`, `a:hover`, `nav > li`) becomes an ambient rule. Inline style= attributes land on the node\'s inline styles. To author or edit CSS on its own — pseudo/hover/descendant selectors, or restyling existing rules — use the dedicated site_apply_css tool instead (site_insert_html is for inserting structure). Returns `nodeIds` (the inserted roots) and `created` — every inserted node as { id, moduleId, classes } — so you can target a nested node (e.g. the wrapper you just added) without re-reading the whole tree.',
+    'Insert semantic HTML as a subtree of editable nodes under an existing parent. Write structure as HTML (<section>, <h1>, <a>, <button>, <img>, <ul>, ...) and style it with CSS in the same call: put a <style> block in the HTML and/or class= attributes. Custom importer markers: <instatic-loop data-source-id="…" ...> creates a real Loop node (call site_list_loop_sources first for source/table ids and {currentEntry.*} tokens; never place the loop inside a <table>, <tbody> or <tr> — HTML parsing moves it out of the table and leaves its rows behind, publishing one blank row. Wrap the whole <table> in the loop, or use a list); <instatic-outlet data-tag="div"> creates a neutral template content outlet. On PAGE routes the outlet element is not rendered at all — the page content is spliced in at its position — so wrap the outlet in <main> yourself if pages should have a main landmark. data-tag only takes effect on ENTRY routes, where the outlet stays and wraps the entry body (use data-custom-tag for a safe custom element). The importer parses every rule — a bare `.foo {}` selector becomes a reusable Selectors-panel class bound to class="foo"; any other selector (`.hero a`, `a:hover`, `nav > li`) becomes an ambient rule. Inline style= attributes land on the node\'s inline styles. To author or edit CSS on its own — pseudo/hover/descendant selectors, or restyling existing rules — use the dedicated site_apply_css tool instead (site_insert_html is for inserting structure). Returns `nodeIds` (the inserted roots) and `created` — every inserted node as { id, moduleId, classes } — so you can target a nested node (e.g. the wrapper you just added) without re-reading the whole tree. `warnings` lists anything the importer dropped or ignored: <script> and on* handlers (write a code asset instead), and <link>/<meta>/<title> head elements, which the site generates from its settings (favicon, title) and never authors as nodes. A payload made only of those is rejected with an error naming them.',
   inputSchema: InsertHtmlInputSchema,
 }
 
@@ -124,7 +124,7 @@ const replaceNodeHtmlTool: AiTool = {
   execution: 'browser',
   requiredCapabilities: SITE_STRUCTURE_CAPS,
   description:
-    "Replace a node subtree's children with new HTML. The target node is preserved as the parent; its existing children are rebuilt from the HTML. Style with CSS exactly as in site_insert_html: a <style> block and/or class= attributes; bare `.foo` selectors become reusable classes, other selectors become ambient rules. Custom importer markers work here too: <instatic-loop data-source-id=\"…\" ...> creates a real Loop node and <instatic-outlet data-tag=\"div\"> creates a neutral template content outlet (omit data-tag only when the outlet should render as main). To author or edit CSS on its own (without rebuilding children), use the dedicated site_apply_css tool instead.",
+    "Replace a node subtree's children with new HTML. The target node is preserved as the parent; its existing children are rebuilt from the HTML. Style with CSS exactly as in site_insert_html: a <style> block and/or class= attributes; bare `.foo` selectors become reusable classes, other selectors become ambient rules. Custom importer markers work here too: <instatic-loop data-source-id=\"…\" ...> creates a real Loop node and <instatic-outlet data-tag=\"div\"> creates a neutral template content outlet (omit data-tag only when the outlet should render as main). To author or edit CSS on its own (without rebuilding children), use the dedicated site_apply_css tool instead. `warnings` lists anything the importer dropped or ignored (<script> and on* handlers, <link>/<meta>/<title> head elements), exactly as site_insert_html does.",
   inputSchema: ReplaceNodeHtmlInputSchema,
 }
 
diff --git a/src/__tests__/agent/executorImportNotices.test.ts b/src/__tests__/agent/executorImportNotices.test.ts
new file mode 100644
index 000000000..78b1e3a04
--- /dev/null
+++ b/src/__tests__/agent/executorImportNotices.test.ts
@@ -0,0 +1,72 @@
+/**
+ * #490 — what the HTML tools say about markup they could not keep.
+ *
+ * Two silent outcomes were reported: `site_replace_node_html` dropped a
+ * `<script>` with no trace in the result, and a head-only payload (a bare
+ * `<link rel="icon">`) came back as "no importable elements" without naming
+ * the element. Both tools now report stripped and ignored constructs, as
+ * `warnings` on success and inside the error when nothing was importable.
+ */
+import { describe, expect, it } from 'bun:test'
+import { useEditorStore } from '@site/store/store'
+import { executeAgentTool } from '@site/agent'
+import '@modules/base'
+
+function freshRoot(): string {
+  useEditorStore.setState({ site: null })
+  const site = useEditorStore.getState().createSite('Test')
+  return site.pages[0].rootNodeId
+}
+
+// The browser parser moves a bare top-level <link> into <head>; the test
+// polyfill only does so for an explicit document, so spell the head out.
+const HEAD_ONLY = '<html><head><link rel="icon" type="image/svg+xml" href="/favicon.svg"></head><body></body></html>'
+
+describe('HTML tool import notices', () => {
+  it('insertHtml names the head-only element instead of a bare "no importable elements"', async () => {
+    const result = await executeAgentTool('site_insert_html', { parentId: freshRoot(), html: HEAD_ONLY })
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('no importable elements')
+    expect(result.error).toContain('<link>')
+    expect(result.error).toContain('<head>')
+  })
+
+  it('replaceNodeHtml reports a stripped <script> as a warning while still inserting the rest', async () => {
+    const rootId = freshRoot()
+    const wrapper = await executeAgentTool('site_insert_html', { parentId: rootId, html: '<div></div>' })
+    const wrapperId = (wrapper.data as { nodeIds: string[] }).nodeIds[0]
+
+    const result = await executeAgentTool('site_replace_node_html', {
+      nodeId: wrapperId,
+      html: '<section><h1>Hi</h1><script>console.log(1)</script></section>',
+    })
+    expect(result.ok).toBe(true)
+    const data = result.data as { nodeIds: string[]; warnings?: string[] }
+    expect(data.nodeIds).toHaveLength(1)
+    expect(data.warnings).toHaveLength(1)
+    expect(data.warnings?.[0]).toContain('1 <script> element')
+    expect(data.warnings?.[0]).toContain('site_write_code_asset')
+  })
+
+  it('insertHtml reports stripped inline handlers and ignored head elements alongside inserted nodes', async () => {
+    const result = await executeAgentTool('site_insert_html', {
+      parentId: freshRoot(),
+      html: '<html><head><meta name="description" content="x"><title>T</title></head>'
+        + '<body><button onclick="go()">Go</button></body></html>',
+    })
+    expect(result.ok).toBe(true)
+    const data = result.data as { warnings?: string[] }
+    expect(data.warnings).toHaveLength(2)
+    expect(data.warnings?.[0]).toContain('1 inline event handler attribute')
+    expect(data.warnings?.[1]).toContain('<meta>, <title>')
+  })
+
+  it('stays silent when nothing was dropped', async () => {
+    const result = await executeAgentTool('site_insert_html', {
+      parentId: freshRoot(),
+      html: '<section><p>Plain</p></section>',
+    })
+    expect(result.ok).toBe(true)
+    expect((result.data as { warnings?: string[] }).warnings).toBeUndefined()
+  })
+})
diff --git a/src/__tests__/htmlImport/headOnlyElements.test.ts b/src/__tests__/htmlImport/headOnlyElements.test.ts
new file mode 100644
index 000000000..88216d80e
--- /dev/null
+++ b/src/__tests__/htmlImport/headOnlyElements.test.ts
@@ -0,0 +1,34 @@
+/**
+ * #490 — a payload the parser places entirely in `<head>` (a bare
+ * `<link rel="icon">` is the reported case) produced an empty fragment and
+ * nothing that said why. `importHtml` now reports those tags as `headOnly`
+ * so callers can name them.
+ */
+import { describe, expect, it } from 'bun:test'
+import '@modules/base'
+import { importHtml } from '@core/htmlImport'
+
+describe('importHtml head-only elements', () => {
+  it('reports head elements by tag, deduplicated, in document order', () => {
+    const result = importHtml(
+      '<!doctype html><html><head><title>T</title><link rel="icon" href="/favicon.svg">'
+      + '<meta charset="utf-8"><link rel="stylesheet" href="x.css"><base href="/"></head><body></body></html>',
+    )
+    expect(result.rootIds).toEqual([])
+    expect(result.headOnly).toEqual(['title', 'link', 'meta', 'base'])
+  })
+
+  it('does not list scripts and styles twice: they have their own report', () => {
+    const result = importHtml(
+      '<html><head><script>1</script><style>.a{color:red}</style><meta name="x" content="y"></head><body><p>hi</p></body></html>',
+    )
+    expect(result.stripped.scripts).toBe(1)
+    expect(result.styleCss).toContain('.a')
+    expect(result.headOnly).toEqual(['meta'])
+    expect(result.rootIds).toHaveLength(1)
+  })
+
+  it('is empty for ordinary body markup', () => {
+    expect(importHtml('<section><h1>Hi</h1></section>').headOnly).toEqual([])
+  })
+})
diff --git a/src/admin/modals/ImportHtml/ImportHtmlModal.tsx b/src/admin/modals/ImportHtml/ImportHtmlModal.tsx
index d46178030..03ee6950a 100644
--- a/src/admin/modals/ImportHtml/ImportHtmlModal.tsx
+++ b/src/admin/modals/ImportHtml/ImportHtmlModal.tsx
@@ -267,11 +267,14 @@ export function ImportHtmlModal() {
       if (rules.length) {
         detailParts.push(`${rules.length} CSS selector${rules.length > 1 ? 's' : ''}`)
       }
-      const { stripped } = result
+      const { stripped, headOnly } = result
       if (stripped.scripts) detailParts.push(`stripped ${stripped.scripts} <script>`)
       if (stripped.inlineHandlers) {
         detailParts.push(`stripped ${stripped.inlineHandlers} inline handler${stripped.inlineHandlers > 1 ? 's' : ''}`)
       }
+      if (headOnly.length) {
+        detailParts.push(`ignored ${headOnly.map((tag) => `<${tag}>`).join(', ')} from <head>`)
+      }
       const toastBody = detailParts.length > 0 ? detailParts.join(', ') : undefined
 
       pushToast({ kind: 'success', title: toastTitle, body: toastBody })
diff --git a/src/admin/pages/site/agent/documentTools.ts b/src/admin/pages/site/agent/documentTools.ts
index 941e84acf..0bdc145eb 100644
--- a/src/admin/pages/site/agent/documentTools.ts
+++ b/src/admin/pages/site/agent/documentTools.ts
@@ -166,3 +166,30 @@ function resolveAgentDocument(
   if (!descriptor) return null
   return { descriptor, page }
 }
+
+/**
+ * Resolve a node by ID **within the active document only** — never across other
+ * pages, templates, or VCs. Write tools mutate the active tree, so resolving an
+ * id that lives in a different document would silently target the wrong tree
+ * (or fail with a misleading "does not accept children"). Returns the node when
+ * it belongs to the active doc, else undefined.
+ */
+export function findNodeInActiveDoc(store: EditorStore, nodeId: string): BaseNode | undefined {
+  return activeDocumentNodes(store)?.[nodeId]
+}
+
+/**
+ * Shared "node not found in the active doc" error: distinguishes a node that
+ * lives in another document (actionable — switch docs) from one that exists
+ * nowhere (a bad id).
+ */
+export function nodeNotInActiveDocError(store: EditorStore, nodeId: string): AiToolOutput {
+  const documentIdError = describeDocumentId(store, nodeId)
+  if (documentIdError) return aiToolError(documentIdError)
+  const foreign = describeForeignNode(store, nodeId)
+  return aiToolError(
+    foreign
+      ? `Node ${nodeId} lives in ${foreign} and could not be activated automatically.`
+      : `Node not found: ${nodeId}`,
+  )
+}
diff --git a/src/admin/pages/site/agent/executor.ts b/src/admin/pages/site/agent/executor.ts
index bb58de022..bd3476ccc 100644
--- a/src/admin/pages/site/agent/executor.ts
+++ b/src/admin/pages/site/agent/executor.ts
@@ -47,11 +47,9 @@ import {
   SetPageTemplateInputSchema,
   ClearPageTemplateInputSchema,
   RenderSnapshotInputSchema,
-  type InsertHtmlInput,
   type GetNodeHtmlInput,
   type ReadDocumentInput,
   type OpenDocumentInput,
-  type ReplaceNodeHtmlInput,
   type DeleteNodeInput,
   type UpdateNodePropsInput,
   type MoveNodeInput,
@@ -69,8 +67,7 @@ import {
 import type { EditorStore } from '@site/store/types'
 import { registry } from '@core/module-engine'
 import { sanitizeRichtext, isRichtextPropKey } from '@core/sanitize'
-import { importHtml } from '@core/htmlImport'
-import type { BaseNode, PageTemplateConfig } from '@core/page-tree'
+import type { PageTemplateConfig } from '@core/page-tree'
 import { renderNode, type RenderConfig, type RenderAccumulators } from '@core/publisher'
 import { getAgentStoreApi } from './storeRef'
 import { whenCollabWritable } from '@site/store/slices/site/collabWriteGate'
@@ -89,13 +86,13 @@ import {
   runWriteCodeAsset,
 } from './codeAssetTools'
 import { runRenderSnapshotAtBreakpoint } from './renderSnapshotAtBreakpoint'
-import { parseImportedStyleCss, runApplyCss } from './cssTools'
+import { runApplyCss } from './cssTools'
+import { runInsertHtml, runReplaceNodeHtml } from './htmlTools'
 import {
-  activeDocumentNodes,
   activeRenderPage,
-  describeDocumentId,
-  describeForeignNode,
+  findNodeInActiveDoc,
   focusNodeDocument,
+  nodeNotInActiveDocError,
   runOpenDocument,
   runReadDocument,
 } from './documentTools'
@@ -163,34 +160,6 @@ function validateBreakpointId(
     : `Breakpoint not found: ${breakpointId}`
 }
 
-/**
- * Resolve a node by ID **within the active document only** — never across other
- * pages, templates, or VCs. Write tools mutate the active tree, so resolving an
- * id that lives in a different document would silently target the wrong tree
- * (or fail with a misleading "does not accept children"). Returns the node when
- * it belongs to the active doc, else undefined.
- */
-function findNodeInActiveDoc(store: EditorStore, nodeId: string): BaseNode | undefined {
-  return activeDocumentNodes(store)?.[nodeId]
-}
-
-/**
- * Shared "node not found in the active doc" error: distinguishes a node that
- * lives in another document (actionable — switch docs) from one that exists
- * nowhere (a bad id).
- */
-function nodeNotInActiveDocError(store: EditorStore, nodeId: string): AiToolOutput {
-  const documentIdError = describeDocumentId(store, nodeId)
-  if (documentIdError) return aiToolError(documentIdError)
-  const foreign = describeForeignNode(store, nodeId)
-  return aiToolError(
-    foreign
-      ? `Node ${nodeId} lives in ${foreign} and could not be activated automatically.`
-      : `Node not found: ${nodeId}`,
-  )
-}
-
-
 /** Pull the node/parent id a write tool targets out of its raw input bag. */
 function targetNodeIdFromInput(raw: unknown): string | undefined {
   if (!raw || typeof raw !== 'object') return undefined
@@ -203,99 +172,6 @@ function targetNodeIdFromInput(raw: unknown): string | undefined {
 // Per-tool implementations
 // ---------------------------------------------------------------------------
 
-/**
- * Insert an HTML snippet as page nodes under `parentId`.
- *
- * Pipeline (identical to the paste-import modal path):
- *   1. importHtml(input.html) — parse → strip unsafe → walkAndMap → fragment
- *      (+ inline `style="…"` on node.inlineStyles, + raw `<style>` CSS).
- *   2. parseImportedStyleCss — `<style>` CSS → registry rules + conditions.
- *      `cssToStyleRules` classifies each selector: a bare `.foo` becomes a
- *      reusable class, anything else (`.hero a`, `a:hover`, …) an ambient rule.
- *   3. insertImportedNodes(parentId, fragment, { index, styleRules, conditions })
- *      — nodes, <style> rules, and class-token binding in one undo step.
- */
-function runInsertHtml(input: InsertHtmlInput): AiToolOutput {
-  // (1) Parse and walk the HTML to produce a flat node fragment + any <style> CSS
-  const { nodes, rootIds, styleCss, stripped, warnings } = importHtml(input.html)
-  const { rules, conditions } = parseImportedStyleCss(styleCss)
-
-  if (rootIds.length === 0) {
-    // A <style>-only payload carries no elements but still carries authorable
-    // CSS — reusable classes and ambient rules (`a:hover`, `.hero a`,
-    // `::before`, …). Upsert them rather than discarding them. (The dedicated
-    // `site_apply_css` tool is the canonical path for this; insertHtml stays forgiving
-    // when a CSS-only payload arrives here.)
-    if (rules.length > 0 || conditions.length > 0) {
-      const result = getStoreState().applyCssRules(rules, conditions, 'merge')
-      if (result.blockedSelectors.length > 0) {
-        return aiToolError(
-          `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
-        )
-      }
-      return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
-    }
-    const scriptHint = stripped.scripts > 0 || stripped.inlineHandlers > 0
-      ? ' Scripts and inline event handlers are stripped from HTML imports; create runtime behavior with site_write_code_asset({ type:"script", ... }) instead.'
-      : ''
-    return aiToolError(`HTML contained no importable elements or style rules.${scriptHint}`)
-  }
-
-  // (2) Insert via the store action — same path as the paste import modal
-  const store = getStoreState()
-  const insertedRootIds = store.insertImportedNodes(
-    input.parentId,
-    { nodes, rootIds },
-    { index: input.index, styleRules: rules, conditions },
-  )
-  if (insertedRootIds.length === 0) {
-    return aiToolError(`Parent node not found or does not accept children: ${input.parentId}`)
-  }
-
-  // Return the full created subtree (id + module + class names) so the caller
-  // can target nested nodes (e.g. the `.ist-shell` wrapper) without a separate
-  // tree dump. `nodeIds` stays as the top-level roots for back-compat.
-  // Read FRESH state after the insert — `store` above is the pre-insert
-  // immutable snapshot, so its node map doesn't contain the new nodes (and its
-  // styleRules lacks any classes insertImportedNodes auto-created).
-  const postState = getStoreState()
-  const nodeMap = activeDocumentNodes(postState) ?? {}
-  const styleRules = postState.site?.styleRules ?? {}
-  const created: Array<{ id: string; moduleId: string; classes: string[] }> = []
-  const visit = (id: string): void => {
-    const node = nodeMap[id]
-    if (!node) return
-    created.push({
-      id,
-      moduleId: node.moduleId,
-      classes: (node.classIds ?? []).map((cid) => styleRules[cid]?.name ?? cid),
-    })
-    for (const childId of node.children) visit(childId)
-  }
-  for (const rootId of insertedRootIds) visit(rootId)
-
-  // `insertedRootIds` are the ids the insert INTENDED to create. If none of
-  // them is in the store afterwards the mutation was refused (collab gate,
-  // offline transport), and reporting those ids would claim a subtree that
-  // does not exist — the caller then builds on nodes the server never saw.
-  if (created.length === 0) {
-    return aiToolError(
-      'Insert was refused before it reached the store, so nothing was created. '
-      + 'The editor is usually still syncing; retry shortly.',
-    )
-  }
-
-  // Report references the importer could not resolve. Without this an
-  // `<instatic-loop>` naming a source that does not exist inserts cleanly,
-  // publishes an empty section, and passes every downstream check — the
-  // caller only finds out by looking at the rendered page.
-  return aiToolOk({
-    nodeIds: insertedRootIds,
-    created,
-    ...(warnings.length > 0 ? { warnings: warnings.map((w) => w.message) } : {}),
-  })
-}
-
 /**
  * Render the subtree at `nodeId` to HTML using the publisher's renderNode.
  * Read-only — no store mutation.
@@ -339,70 +215,6 @@ function runOpenDocumentTool(input: OpenDocumentInput): AiToolOutput {
   return runOpenDocument(input, getStoreState())
 }
 
-/**
- * Replace the children of `nodeId` with an HTML snippet.
- *
- * The target node itself is preserved as the parent container. Its current
- * children (and their full subtrees) are deleted, then the imported HTML is
- * inserted in their place.
- */
-function runReplaceNodeHtml(input: ReplaceNodeHtmlInput): AiToolOutput {
-  const store = getStoreState()
-  if (!store.site) return aiToolError('No active site.')
-
-  // Verify the target node exists IN THE ACTIVE DOCUMENT — the only tree this
-  // mutation can touch. A node from another page/template/VC must not resolve.
-  const targetNode = findNodeInActiveDoc(store, input.nodeId)
-  if (!targetNode) {
-    return nodeNotInActiveDocError(store, input.nodeId)
-  }
-
-  // Parse + validate the payload BEFORE mutating, so an empty / invalid payload
-  // never wipes the node's existing children first and then errors out.
-  const { nodes, rootIds, styleCss, stripped, warnings } = importHtml(input.html)
-  const { rules, conditions } = parseImportedStyleCss(styleCss)
-
-  if (rootIds.length === 0) {
-    // A <style>-only payload has nothing to replace the children WITH, so leave
-    // the subtree intact and just upsert its rules — same forgiving behaviour
-    // as insertHtml. Wiping children to insert nothing would be surprising.
-    if (rules.length > 0 || conditions.length > 0) {
-      const result = getStoreState().applyCssRules(rules, conditions, 'merge')
-      if (result.blockedSelectors.length > 0) {
-        return aiToolError(
-          `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
-        )
-      }
-      return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
-    }
-    const scriptHint = stripped.scripts > 0 || stripped.inlineHandlers > 0
-      ? ' Scripts and inline event handlers are stripped from HTML imports; create runtime behavior with site_write_code_asset({ type:"script", ... }) instead.'
-      : ''
-    return aiToolError(`HTML contained no importable elements or style rules.${scriptHint}`)
-  }
-
-  // Delete existing children so the target node is empty before insertion.
-  const existingChildren = [...(targetNode.children ?? [])]
-  if (existingChildren.length > 0) {
-    getStoreState().deleteNodes(existingChildren)
-  }
-
-  const insertedRootIds = getStoreState().insertImportedNodes(
-    input.nodeId,
-    { nodes, rootIds },
-    { styleRules: rules, conditions },
-  )
-  if (insertedRootIds.length === 0) {
-    return aiToolError(`Node does not accept children: ${input.nodeId}`)
-  }
-
-  // Same unresolved-reference report as insertHtml.
-  return aiToolOk({
-    nodeIds: insertedRootIds,
-    ...(warnings.length > 0 ? { warnings: warnings.map((w) => w.message) } : {}),
-  })
-}
-
 function runDeleteNode(input: DeleteNodeInput): AiToolOutput {
   getStoreState().deleteNode(input.nodeId)
   return aiToolOk()
diff --git a/src/admin/pages/site/agent/htmlTools.ts b/src/admin/pages/site/agent/htmlTools.ts
new file mode 100644
index 000000000..3690fc2da
--- /dev/null
+++ b/src/admin/pages/site/agent/htmlTools.ts
@@ -0,0 +1,222 @@
+/**
+ * The two HTML-payload tools, `site_insert_html` and `site_replace_node_html`.
+ *
+ * Both run the pipeline the paste-import modal uses (`importHtml`, then
+ * `parseImportedStyleCss`, then `insertImportedNodes`) and report the same
+ * things back: unresolved importer references, stripped `<script>` / `on*`
+ * handlers, and the head-only elements the parser kept out of the body (#490).
+ */
+import {
+  aiToolError,
+  aiToolOk,
+  type AiToolOutput,
+  type InsertHtmlInput,
+  type ReplaceNodeHtmlInput,
+} from '@core/ai'
+import type { EditorStore } from '@site/store/types'
+import { importHtml, type ImportResult } from '@core/htmlImport'
+import { getAgentStoreApi } from './storeRef'
+import { parseImportedStyleCss } from './cssTools'
+import { activeDocumentNodes, findNodeInActiveDoc, nodeNotInActiveDocError } from './documentTools'
+
+// Live access to the editor store, routed through `./storeRef` like the executor.
+const getStoreState = (): EditorStore => getAgentStoreApi<EditorStore>().getState()
+
+// ---------------------------------------------------------------------------
+// Import diagnostics shared by insertHtml / replaceNodeHtml
+// ---------------------------------------------------------------------------
+
+/**
+ * Everything the importer dropped or ignored, as caller-facing sentences.
+ * Reported on success as `warnings` and folded into the error when nothing
+ * was importable, so a `<script>` inside otherwise valid markup no longer
+ * vanishes silently and a head-only payload says which element it was (#490).
+ */
+function importNotices(result: ImportResult): string[] {
+  const notices: string[] = []
+  const { stripped, headOnly } = result
+  if (stripped.scripts > 0) {
+    notices.push(
+      `Stripped ${stripped.scripts} <script> element${stripped.scripts === 1 ? '' : 's'}: scripts are not page nodes. `
+      + 'Create runtime behaviour with site_write_code_asset({ type: "script", ... }) instead.',
+    )
+  }
+  if (stripped.inlineHandlers > 0) {
+    notices.push(
+      `Stripped ${stripped.inlineHandlers} inline event handler attribute${stripped.inlineHandlers === 1 ? '' : 's'} (on*): `
+      + 'bind behaviour from a code asset instead.',
+    )
+  }
+  if (headOnly.length > 0) {
+    notices.push(
+      `Ignored ${headOnly.map((tag) => `<${tag}>`).join(', ')}: these belong in the document <head>, which the site generates `
+      + 'from its settings (favicon, title, meta), so they cannot be inserted as page nodes.',
+    )
+  }
+  return notices
+}
+
+function noImportableElementsError(result: ImportResult): AiToolOutput {
+  return aiToolError(
+    ['HTML contained no importable elements or style rules.', ...importNotices(result)].join(' '),
+  )
+}
+
+/** Importer reference warnings plus the strip / head-only notices, or nothing. */
+function importWarningsField(result: ImportResult): { warnings?: string[] } {
+  const warnings = [...result.warnings.map((w) => w.message), ...importNotices(result)]
+  return warnings.length > 0 ? { warnings } : {}
+}
+
+/**
+ * Insert an HTML snippet as page nodes under `parentId`.
+ *
+ * Pipeline (identical to the paste-import modal path):
+ *   1. importHtml(input.html) — parse → strip unsafe → walkAndMap → fragment
+ *      (+ inline `style="…"` on node.inlineStyles, + raw `<style>` CSS).
+ *   2. parseImportedStyleCss — `<style>` CSS → registry rules + conditions.
+ *      `cssToStyleRules` classifies each selector: a bare `.foo` becomes a
+ *      reusable class, anything else (`.hero a`, `a:hover`, …) an ambient rule.
+ *   3. insertImportedNodes(parentId, fragment, { index, styleRules, conditions })
+ *      — nodes, <style> rules, and class-token binding in one undo step.
+ */
+export function runInsertHtml(input: InsertHtmlInput): AiToolOutput {
+  // (1) Parse and walk the HTML to produce a flat node fragment + any <style> CSS
+  const imported = importHtml(input.html)
+  const { nodes, rootIds, styleCss } = imported
+  const { rules, conditions } = parseImportedStyleCss(styleCss)
+
+  if (rootIds.length === 0) {
+    // A <style>-only payload carries no elements but still carries authorable
+    // CSS — reusable classes and ambient rules (`a:hover`, `.hero a`,
+    // `::before`, …). Upsert them rather than discarding them. (The dedicated
+    // `site_apply_css` tool is the canonical path for this; insertHtml stays forgiving
+    // when a CSS-only payload arrives here.)
+    if (rules.length > 0 || conditions.length > 0) {
+      const result = getStoreState().applyCssRules(rules, conditions, 'merge')
+      if (result.blockedSelectors.length > 0) {
+        return aiToolError(
+          `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+        )
+      }
+      return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
+    }
+    return noImportableElementsError(imported)
+  }
+
+  // (2) Insert via the store action — same path as the paste import modal
+  const store = getStoreState()
+  const insertedRootIds = store.insertImportedNodes(
+    input.parentId,
+    { nodes, rootIds },
+    { index: input.index, styleRules: rules, conditions },
+  )
+  if (insertedRootIds.length === 0) {
+    return aiToolError(`Parent node not found or does not accept children: ${input.parentId}`)
+  }
+
+  // Return the full created subtree (id + module + class names) so the caller
+  // can target nested nodes (e.g. the `.ist-shell` wrapper) without a separate
+  // tree dump. `nodeIds` stays as the top-level roots for back-compat.
+  // Read FRESH state after the insert — `store` above is the pre-insert
+  // immutable snapshot, so its node map doesn't contain the new nodes (and its
+  // styleRules lacks any classes insertImportedNodes auto-created).
+  const postState = getStoreState()
+  const nodeMap = activeDocumentNodes(postState) ?? {}
+  const styleRules = postState.site?.styleRules ?? {}
+  const created: Array<{ id: string; moduleId: string; classes: string[] }> = []
+  const visit = (id: string): void => {
+    const node = nodeMap[id]
+    if (!node) return
+    created.push({
+      id,
+      moduleId: node.moduleId,
+      classes: (node.classIds ?? []).map((cid) => styleRules[cid]?.name ?? cid),
+    })
+    for (const childId of node.children) visit(childId)
+  }
+  for (const rootId of insertedRootIds) visit(rootId)
+
+  // `insertedRootIds` are the ids the insert INTENDED to create. If none of
+  // them is in the store afterwards the mutation was refused (collab gate,
+  // offline transport), and reporting those ids would claim a subtree that
+  // does not exist — the caller then builds on nodes the server never saw.
+  if (created.length === 0) {
+    return aiToolError(
+      'Insert was refused before it reached the store, so nothing was created. '
+      + 'The editor is usually still syncing; retry shortly.',
+    )
+  }
+
+  // Report references the importer could not resolve and anything it dropped.
+  // Without this an `<instatic-loop>` naming a source that does not exist
+  // inserts cleanly, publishes an empty section, and passes every downstream
+  // check — the caller only finds out by looking at the rendered page.
+  return aiToolOk({
+    nodeIds: insertedRootIds,
+    created,
+    ...importWarningsField(imported),
+  })
+}
+
+/**
+ * Replace the children of `nodeId` with an HTML snippet.
+ *
+ * The target node itself is preserved as the parent container. Its current
+ * children (and their full subtrees) are deleted, then the imported HTML is
+ * inserted in their place.
+ */
+export function runReplaceNodeHtml(input: ReplaceNodeHtmlInput): AiToolOutput {
+  const store = getStoreState()
+  if (!store.site) return aiToolError('No active site.')
+
+  // Verify the target node exists IN THE ACTIVE DOCUMENT — the only tree this
+  // mutation can touch. A node from another page/template/VC must not resolve.
+  const targetNode = findNodeInActiveDoc(store, input.nodeId)
+  if (!targetNode) {
+    return nodeNotInActiveDocError(store, input.nodeId)
+  }
+
+  // Parse + validate the payload BEFORE mutating, so an empty / invalid payload
+  // never wipes the node's existing children first and then errors out.
+  const imported = importHtml(input.html)
+  const { nodes, rootIds, styleCss } = imported
+  const { rules, conditions } = parseImportedStyleCss(styleCss)
+
+  if (rootIds.length === 0) {
+    // A <style>-only payload has nothing to replace the children WITH, so leave
+    // the subtree intact and just upsert its rules — same forgiving behaviour
+    // as insertHtml. Wiping children to insert nothing would be surprising.
+    if (rules.length > 0 || conditions.length > 0) {
+      const result = getStoreState().applyCssRules(rules, conditions, 'merge')
+      if (result.blockedSelectors.length > 0) {
+        return aiToolError(
+          `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+        )
+      }
+      return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
+    }
+    return noImportableElementsError(imported)
+  }
+
+  // Delete existing children so the target node is empty before insertion.
+  const existingChildren = [...(targetNode.children ?? [])]
+  if (existingChildren.length > 0) {
+    getStoreState().deleteNodes(existingChildren)
+  }
+
+  const insertedRootIds = getStoreState().insertImportedNodes(
+    input.nodeId,
+    { nodes, rootIds },
+    { styleRules: rules, conditions },
+  )
+  if (insertedRootIds.length === 0) {
+    return aiToolError(`Node does not accept children: ${input.nodeId}`)
+  }
+
+  // Same unresolved-reference and stripped-construct report as insertHtml.
+  return aiToolOk({
+    nodeIds: insertedRootIds,
+    ...importWarningsField(imported),
+  })
+}
diff --git a/src/core/htmlImport/walkAndMap.ts b/src/core/htmlImport/walkAndMap.ts
index 7e0ff7be2..9c9d94c69 100644
--- a/src/core/htmlImport/walkAndMap.ts
+++ b/src/core/htmlImport/walkAndMap.ts
@@ -94,6 +94,15 @@ interface ImportBodyAttributes {
 export interface ImportResult extends WalkResult {
   /** Counts of constructs stripped by stripUnsafe(). */
   stripped: StripReport
+  /**
+   * Tag names (deduplicated, document order) of elements the HTML parser
+   * placed in `<head>` and the walker therefore never saw: `link`, `meta`,
+   * `title`, `base`, … A bare `<link rel="icon">` at the top of a payload
+   * lands here in every browser, so a caller that only checks `rootIds`
+   * would report "nothing importable" without saying why (#490). `<script>`
+   * and `<style>` are already stripped / harvested before this is read.
+   */
+  headOnly: string[]
   /**
    * Raw concatenated CSS harvested from `<style>` blocks in the source. Empty
    * when the source had none. The consumer parses it via `cssToStyleRules`
@@ -429,9 +438,10 @@ export function walkAndMap(
  * 5. walkAndMap  — maps every element to a PageNode via HTML_TO_MODULE_RULES,
  *    attaching the harvested inline styles to its node's `inlineStyles`
  *
- * Returns an ImportResult that merges the fragment with the StripReport and the
- * raw `<style>` CSS, so callers can parse the CSS into registry rules and
- * surface a "Stripped: N scripts, M handlers" toast.
+ * Returns an ImportResult that merges the fragment with the StripReport, the
+ * head-only elements the walk never saw, and the raw `<style>` CSS, so callers
+ * can parse the CSS into registry rules and tell the author what was stripped
+ * or ignored.
  */
 export function importHtml(source: string): ImportResult {
   const doc = parseHtml(source)
@@ -439,6 +449,11 @@ export function importHtml(source: string): ImportResult {
   const inlineStyles = harvestInlineStyles(doc)
   const styleCss = collectStyleCss(doc)
   const stripped = stripUnsafe(doc)
+  // Read after the strip so scripts and styles, which have their own report,
+  // are not listed twice.
+  const headOnly = [...new Set(
+    Array.from(doc.head?.children ?? []).map((el) => el.tagName.toLowerCase()),
+  )]
   const fragment = walkAndMap(doc, inlineStyles)
-  return { ...fragment, stripped, styleCss }
+  return { ...fragment, stripped, headOnly, styleCss }
 }