From f4684d4b032825ff99987c9ca65f446f07d5ffe8 Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Fri, 14 Aug 2026 16:01:04 -0500
Subject: [PATCH 1/6] Investigate bd-format-css-not-copied-crn3bjdz:
 format.html.css neither copied nor rebased

Plan skeleton + minimal repro fixture. Both defects confirmed at HEAD
(10d86829): declared css files never written to _site, hrefs emitted
verbatim at every page depth beside correctly-rebased site_libs links,
no diagnostic. Verdict: ready to design; open questions on output
layout (Q1 site_libs/quarto-contrib parity vs project-relative copy),
rebase mechanism (Path-kind metadata marking vs resource resolver),
and scope (books, js/format-resources, doc-level css).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-14-format-css-not-copied.md | 199 ++++++++++++++++++
 .../README.md                                 |  29 +++
 .../repro/_extensions/acme/widget/widget.css  |   1 +
 .../repro/_quarto.yml                         |   9 +
 .../repro/deep/deeper/index.qmd               |   5 +
 .../repro/index.qmd                           |   5 +
 .../repro/styles.css                          |   1 +
 7 files changed, 249 insertions(+)
 create mode 100644 claude-notes/plans/2026-08-14-format-css-not-copied.md
 create mode 100644 claude-notes/plans/format-css-not-copied-investigation/README.md
 create mode 100644 claude-notes/plans/format-css-not-copied-investigation/repro/_extensions/acme/widget/widget.css
 create mode 100644 claude-notes/plans/format-css-not-copied-investigation/repro/_quarto.yml
 create mode 100644 claude-notes/plans/format-css-not-copied-investigation/repro/deep/deeper/index.qmd
 create mode 100644 claude-notes/plans/format-css-not-copied-investigation/repro/index.qmd
 create mode 100644 claude-notes/plans/format-css-not-copied-investigation/repro/styles.css

diff --git a/claude-notes/plans/2026-08-14-format-css-not-copied.md b/claude-notes/plans/2026-08-14-format-css-not-copied.md
new file mode 100644
index 000000000..251817a21
--- /dev/null
+++ b/claude-notes/plans/2026-08-14-format-css-not-copied.md
@@ -0,0 +1,199 @@
+# format.html.css files are neither copied into the site nor rebased per page (bd-format-css-not-copied-crn3bjdz)
+
+**Date:** 2026-08-14
+**Braid:** bd-format-css-not-copied-crn3bjdz (bug, p1, label `websites`)
+**Checkout:** main checkout, branch `main` @ `10d86829` (investigation only — no worktree/branch created)
+**Status:** Investigation — pending design alignment with user. **Do not start implementation until the user gives the go-ahead.**
+
+## Triage verdict
+
+**Ready to design.** The symptom reproduces at HEAD, both halves of the fix
+have direct in-tree precedent (favicon copy + Path-kind metadata rebase /
+resource-resolver href resolution), and the remaining decisions are genuine
+design choices (output layout, which rebase mechanism, scope), not missing
+information.
+
+## Issue context
+
+Filed 2026-08-14 by the q2-connect-docs porting session (origin strand in that
+skein: br-format-css-not-copied-4jnxbq38). A website project declaring
+
+```yaml
+format:
+  html:
+    css:
+      - styles.css
+      - _extensions/acme/widget/widget.css
+```
+
+gets a `<link>` to each file on every page, but:
+
+1. **Not copied** — neither file is written into `_site/`, so every link
+   404s. No diagnostic; exit 0. Q1 copies both (project css to
+   `_site/styles.css`; extension-owned css to
+   `site_libs/quarto-contrib/quarto-project/acme/widget/widget.css`).
+2. **Not rebased** — the href is emitted verbatim at every depth
+   (`styles.css` on `deep/deeper/index.html`, where Q1 emits
+   `../../styles.css`). The built-in theme stylesheets on the same page *are*
+   rebased — that asymmetry is the control.
+
+Real-world impact: all 352 rendered pages of the Posit Connect docs port link
+two nonexistent stylesheets (704 broken references). Invisible to text-diff
+sweeps because CSS contributes no text.
+
+Not the same as bd-of20unsb (extension `contributes.formats` fragment paths,
+fixed in 0.21.0): here the paths live in the project's own `_quarto.yml`; the
+second one merely points into `_extensions/`. Notably, the repro's
+`_extensions/acme/widget/` contains **only** `widget.css` — no
+`_extension.yml` — so no extension machinery is involved at all.
+
+## Dependency graph
+
+**Empty** — no edges in the skein (strand is hours old). Context instead
+comes from the strands the description references:
+
+- **bd-root-relative-paths-design-fc5pvkcv** (in_progress, design) — the
+  navbar-logo/root-absolute-path design session. Its Decision 5 ("favicon is
+  not special — config-declared assets q2 knows about get the same
+  warn-and-continue copy treatment") is the stated policy this bug falls
+  under. Its case-A fix (0.21.0) built `copy_navbar_logo` /
+  `copy_footer_images` on the shared `copy_asset_file` helper — the exact
+  seam to extend.
+- **bd-of20unsb** (in_progress; fix shipped in 0.21.0 per repro README) —
+  extension-fragment path rebasing. Its mechanism (mark values as
+  `ConfigValueKind::Path`, existence-driven, then let the metadata merge
+  rebase them per document) is one of the two candidate mechanisms for the
+  rebase half here.
+
+## What the code looks like today
+
+All paths verified at `main` @ `10d86829`:
+
+- **Link emission**: `extract_css_from_meta`
+  (`crates/quarto-core/src/template.rs:928`) reads the `css` metadata key
+  (scalar / PandocInlines / array) and appends the strings **verbatim** to
+  the template `css` list (`render_with_compiled_template`,
+  `template.rs:699-709`). No resolver, no copy, no existence check.
+- **Why theme css *is* rebased**: built-in stylesheets are artifacts;
+  `ApplyTemplateStage` computes their URLs via the per-page
+  `ResourceResolverContext` (`apply_template.rs:166`,
+  `collect_artifact_urls`). User css never touches that path.
+- **Copy boundary**: `crates/quarto-core/src/project/website_post_render.rs`
+  has `copy_favicon`, `copy_navbar_logo`, `copy_footer_images`, all sharing
+  `copy_asset_file` and the warn-on-missing-source pattern. `format.html.css`
+  has no counterpart. (All native-only; the in-browser preview has no on-disk
+  output dir.)
+- **Href precedent (per-page transform)**: `WebsiteFaviconTransform`
+  (`transforms/website_favicon.rs`) resolves a page-relative href through
+  `ctx.resource_resolver` and appends the `<link>` to
+  `rendered.includes.header`.
+- **Rebase precedent (metadata merge)**: `FRAGMENT_PATH_PATTERNS`
+  (`project/mod.rs:696`) already lists `["format", "*", "css"]` — but only
+  for **extension** `contributes.project` fragments. Values marked
+  `ConfigValueKind::Path` are rebased project-root → document-dir by
+  `adjust_paths_to_document_dir` during the metadata merge
+  (`metadata_merge.rs:256` applies it to the project-config layer). The
+  project's own `_quarto.yml` values are never *marked* Path-kind, so the
+  machinery never fires for them.
+- **Resource collector**: `resource_collector.rs` walks the AST only;
+  metadata-declared css is invisible to it (same blind spot the design
+  strand documents for raw HTML).
+
+### Repro at HEAD
+
+Fixture: `claude-notes/plans/format-css-not-copied-investigation/repro/`
+(mirrors the external repro at
+`~/repos/github/cscheid/q2-connect-docs/llms-info/repros/format-css-not-copied/`).
+
+Run 2026-08-14 at `main` @ `10d86829` (pre-flight `cargo xtask verify
+--skip-hub-build` green, 12167/12167):
+
+```
+cargo run --bin q2 -- render claude-notes/plans/format-css-not-copied-investigation/repro
+# → "Rendered 2 of 2 files", exit 0, no diagnostic
+```
+
+Observed output (inspected directly):
+
+- `_site/styles.css`: **does not exist**; no css file anywhere in `_site`
+  besides `site_libs/` assets. Marker custom properties absent from the
+  theme bundle — the declared css is dropped entirely.
+- `_site/index.html` links: `site_libs/…` (fine), then verbatim
+  `href="styles.css"` and `href="_extensions/acme/widget/widget.css"` —
+  both 404.
+- `_site/deep/deeper/index.html`: `../../site_libs/…` (rebased correctly)
+  immediately beside verbatim `href="styles.css"` /
+  `href="_extensions/acme/widget/widget.css"` — the asymmetry the strand
+  describes, confirmed on one page.
+
+Both defects confirmed; matches the external repro's table for q2 0.21.0.
+
+## Proposed phases (draft)
+
+Skeleton only — actual phase contents wait on the design discussion.
+
+- **Phase 0 — Test plan (TDD).** End-to-end website render tests driving the
+  real project pipeline: (a) `_site/styles.css` exists after render;
+  (b) extension-path css exists at the decided output location; (c) deep
+  page's `<link href>` is depth-correct; (d) missing declared css warns
+  (and root page still renders); (e) external URL entries pass through
+  untouched. Verify each fails at HEAD first.
+- **Phase 1 — Copy.** `copy_format_css` in `website_post_render.rs` on the
+  `copy_asset_file` seam; iterate merged `format.html.css` entries; skip
+  external URLs; warn on missing source (favicon parity).
+- **Phase 2 — Rebase.** Per-page depth-correct hrefs via the chosen
+  mechanism (design question 2).
+- **Phase 3 — Diagnostic.** Warning for missing declared css; decide plain
+  warning vs. Q-code (a Q-code requires the docs page in the same commit —
+  `error-docs-page-missing` lint).
+- **Phase 4 — End-to-end verification + docs.** Render the fixture through
+  `cargo run --bin q2 -- render`, inspect output, re-check the Connect docs
+  repro; user-facing docs if any behavior is documented.
+
+## Open design questions for the user
+
+1. **Output layout for css under `_extensions/`.** Q1 relocates
+   extension-owned css to
+   `site_libs/quarto-contrib/quarto-project/<org>/<ext>/…` and rewrites the
+   href accordingly. The simpler alternative is to copy preserving the
+   project-relative path (`_site/_extensions/acme/widget/widget.css`) and
+   emit the rebased href to that. Q1 parity, or the simpler layout? (Q1
+   avoids copying `_extensions/` into output wholesale; do we care about
+   that convention here?)
+2. **Rebase mechanism.** Two candidates with in-tree precedent:
+   (a) mark project-config `format.*.css` entries as `ConfigValueKind::Path`
+   (existence-driven, like extension fragments) and let the existing
+   `adjust_paths_to_document_dir` merge machinery emit document-relative
+   values — near-zero new code, but couples href shape to the input tree
+   mirroring the output tree; or (b) resolve at template/transform time via
+   the per-page `ResourceResolverContext`, like the favicon and theme
+   bundle — more explicit, and the same seam a later `site_libs` relocation
+   (question 1) would need anyway. Which?
+3. **Scope beyond `css`.** The same boundary presumably affects sibling
+   config-declared assets (`include-in-header` files are inlined so likely
+   fine, but what about `format-resources`, user `js`/`scripts` entries, and
+   document-level `css:` declared in a subdirectory page's front matter —
+   resolved against the document dir?). Fix `css` only here and file
+   follow-ups, or audit the boundary in this strand?
+4. **Diagnostic shape.** Favicon uses a plain `DiagnosticMessage::warning`.
+   Same here, or mint a Q-code (requires `docs/errors/` page + catalog entry
+   in the same commit)?
+5. **Preview parity.** `website_post_render` hooks are native-only. Does the
+   in-browser preview / `q2 preview` serve declared css from the source tree
+   already (VFS), or does preview need its own leg? (Fine to answer "verify
+   during Phase 4 and file a follow-up if broken.")
+
+## Risks / tradeoffs (draft)
+
+- **Book projects** likely share the symptom (same template path); fixing
+  only the website post-render hook would leave books broken. Worth checking
+  where books' post-render lives before committing to the seam.
+- Choosing rebase mechanism (a) silently changes the merged metadata value
+  shape (`Scalar` → `Path`) for a user-visible key; downstream readers of
+  `css` metadata (Lua filters, template contexts) would observe rewritten
+  values. Mechanism (b) keeps metadata untouched.
+- The design strand bd-root-relative-paths-design-fc5pvkcv is still
+  in_progress; its remaining case C (raw HTML) is independent, but any
+  decision here should cite its Decision 4/5 vocabulary (leading `/` =
+  site-root-relative; config-declared assets get warn-and-continue copy) to
+  stay consistent.
diff --git a/claude-notes/plans/format-css-not-copied-investigation/README.md b/claude-notes/plans/format-css-not-copied-investigation/README.md
new file mode 100644
index 000000000..ac6b4f106
--- /dev/null
+++ b/claude-notes/plans/format-css-not-copied-investigation/README.md
@@ -0,0 +1,29 @@
+# Investigation artifacts for bd-format-css-not-copied-crn3bjdz
+
+`repro/` is a minimal website project mirroring the external repro at
+`~/repos/github/cscheid/q2-connect-docs/llms-info/repros/format-css-not-copied/`
+(source of truth for the Q1 comparison table).
+
+Run:
+
+```bash
+cargo run --bin q2 -- render claude-notes/plans/format-css-not-copied-investigation/repro
+```
+
+Expected (buggy) behavior at `main` @ `10d86829`, confirmed 2026-08-14:
+
+- `_site/styles.css` and the extension css are **not written** anywhere in
+  the output tree;
+- both `<link>` hrefs are emitted **verbatim at every depth**
+  (`styles.css` on `deep/deeper/index.html`, beside a correctly rebased
+  `../../site_libs/quarto/quarto-theme-*.css`);
+- render is clean: exit 0, no diagnostic.
+
+Note `_extensions/acme/widget/` deliberately contains only `widget.css` —
+no `_extension.yml` — so no extension machinery is involved; the path just
+happens to point into `_extensions/`.
+
+The rendered `_site/` is not committed; re-render to regenerate.
+
+See `claude-notes/plans/2026-08-14-format-css-not-copied.md` for the full
+investigation and design questions.
diff --git a/claude-notes/plans/format-css-not-copied-investigation/repro/_extensions/acme/widget/widget.css b/claude-notes/plans/format-css-not-copied-investigation/repro/_extensions/acme/widget/widget.css
new file mode 100644
index 000000000..d62fc614b
--- /dev/null
+++ b/claude-notes/plans/format-css-not-copied-investigation/repro/_extensions/acme/widget/widget.css
@@ -0,0 +1 @@
+body { --repro-extension-css: 1; }
diff --git a/claude-notes/plans/format-css-not-copied-investigation/repro/_quarto.yml b/claude-notes/plans/format-css-not-copied-investigation/repro/_quarto.yml
new file mode 100644
index 000000000..83fa71df8
--- /dev/null
+++ b/claude-notes/plans/format-css-not-copied-investigation/repro/_quarto.yml
@@ -0,0 +1,9 @@
+project:
+  type: website
+website:
+  title: "format css"
+format:
+  html:
+    css:
+      - styles.css
+      - _extensions/acme/widget/widget.css
diff --git a/claude-notes/plans/format-css-not-copied-investigation/repro/deep/deeper/index.qmd b/claude-notes/plans/format-css-not-copied-investigation/repro/deep/deeper/index.qmd
new file mode 100644
index 000000000..ebae7f577
--- /dev/null
+++ b/claude-notes/plans/format-css-not-copied-investigation/repro/deep/deeper/index.qmd
@@ -0,0 +1,5 @@
+---
+title: Deep page
+---
+
+Two directories below the site root.
diff --git a/claude-notes/plans/format-css-not-copied-investigation/repro/index.qmd b/claude-notes/plans/format-css-not-copied-investigation/repro/index.qmd
new file mode 100644
index 000000000..d5dafb9ef
--- /dev/null
+++ b/claude-notes/plans/format-css-not-copied-investigation/repro/index.qmd
@@ -0,0 +1,5 @@
+---
+title: Root page
+---
+
+At the site root.
diff --git a/claude-notes/plans/format-css-not-copied-investigation/repro/styles.css b/claude-notes/plans/format-css-not-copied-investigation/repro/styles.css
new file mode 100644
index 000000000..8c311d5ac
--- /dev/null
+++ b/claude-notes/plans/format-css-not-copied-investigation/repro/styles.css
@@ -0,0 +1 @@
+body { --repro-project-css: 1; }

From 5da9fcee391136642fc106961c6108fa4b640aab Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Fri, 14 Aug 2026 16:20:30 -0500
Subject: [PATCH 2/6] bd-format-css-not-copied-crn3bjdz: evidence passes +
 refined plan

Record user design decisions; add Q1 (quarto-cli) evidence for the
site_libs/quarto-contrib/quarto-project relocation rationale and the
metadata-time rebase mechanism (toInputRelativePaths); add q2 boundary
audit (revealjs drops user css entirely; format-resources accepted but
never consumed; books use DefaultProjectType with no post-render).
Propose hybrid mechanism (merge-time Path marking + render-time
resolver transform); four follow-up questions (F1-F4) pending.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-14-format-css-not-copied.md | 313 ++++++++++++++----
 1 file changed, 254 insertions(+), 59 deletions(-)

diff --git a/claude-notes/plans/2026-08-14-format-css-not-copied.md b/claude-notes/plans/2026-08-14-format-css-not-copied.md
index 251817a21..5fe82bc89 100644
--- a/claude-notes/plans/2026-08-14-format-css-not-copied.md
+++ b/claude-notes/plans/2026-08-14-format-css-not-copied.md
@@ -128,70 +128,265 @@ Observed output (inspected directly):
 
 Both defects confirmed; matches the external repro's table for q2 0.21.0.
 
+## Evidence pass 1: how and why Q1 organizes the output (external-sources/quarto-cli)
+
+Two separate machineries, plus a website-only patch; `css:` straddles them.
+
+**Rebase (metadata-time, not DOM-time).** Q1 runs pandoc with
+`cwd = dirname(input)` (`src/command/render/pandoc.ts:371-372`), so every
+relative path in the defaults file must be input-dir-relative. Project-config
+paths are authored project-relative, so Q1 rewrites them at metadata-merge
+time: `toInputRelativePaths` (`src/project/project-shared.ts:138-207`), called
+from `projectMetadataForInputFile` (`render-contexts.ts:741-757`). It is a
+blind recursive walk over the whole merged config: any non-absolute string
+that names an existing file under the project dir becomes
+`<offset>/<value>` (`offset = relative(inputDir, baseDir)`) — that is the
+entire story of `../../styles.css`. **Existence-driven, layer-aware (the
+same function runs per layer: project config, `_metadata.yml` with the
+metadata file's dir, extension config with the extension dir as base).**
+The HTML template then emits the string verbatim
+(`resources/formats/html/pandoc/html.template:23-24`). The deno-dom
+postprocessor never rewrites a plain relative `css` href — it only records
+it as a resource ref.
+
+**Copy (resource-ref mirror).** The website HTML postprocessor collects every
+resource-tag href; refs are resolved to absolute paths and mirrored:
+`join(formatOutputDir, relative(projDir, file))`
+(`src/command/render/project.ts:735-766`). So project-root css lands at
+`_site/styles.css` purely because resource copying is a project-relative
+mirror. `copyResourceFile` also chases `url()`/`@import` inside copied css
+(`project-resources.ts:110-138`).
+
+**The `_extensions` relocation (website/book-only).**
+`projectExtensionPathResolver` (`src/extension/extension.ts:158-189`) is a
+resolver injected into the website postprocessor: an href resolving under
+`_extensions/` is copied to
+`<lib_dir>/quarto-contrib/quarto-project/<path-with-_extensions-stripped>`
+and the DOM attribute rewritten. Rationale, from the code and introducing
+commits (`364eb9a2d`, `b1e866553`):
+
+1. Underscore-prefixed dirs are systematically non-output
+   (`projectHiddenIgnoreGlob`, `project-context.ts:878-886` — the same list
+   that excludes `README.*`, `CLAUDE.md`, `AGENTS.md`). Publishing
+   `_site/_extensions/` would leak Lua sources, `_extension.yml`, READMEs;
+   relocating means only individually-referenced files ship. This matches
+   the user's stated constraint exactly.
+2. The lib dir is freezer-managed and pruned by a whitelist of known names
+   (`formatLibDirs`, `project-default.ts:23-29`); `quarto-contrib` is the
+   single reserved namespace that protects third-party content without
+   enumerating extension names. `quarto-project` is a fixed literal meaning
+   "the project itself is the contributor" (used when a file is referenced
+   by raw path rather than through a named HTML dependency). There is no
+   per-org namespace logic — the `_extensions` prefix is stripped and the
+   remainder (org segment included) preserved verbatim.
+
+**Book = website machinery** (`book.ts:74` inherits, `book.ts:225-243`
+merges website formatExtras), so the relocation applies there too.
+Single-doc renders never rebase (no project offset) and never relocate;
+lib assets go to `<stem>_files/libs/`. Notably, a *default*-type project
+with an `output-dir` mirrors `_extensions/...` css into the output
+verbatim in Q1 — the relocation is deliberately a website/book behavior.
+
+**Other keys (Q1):** `include-*` files are inlined by pandoc (never
+copied); `format-resources` are flattened **basename-only** next to the
+output — they exist for writers that want sibling files (LaTeX `.cls`,
+Typst), not for `<link>`s; `theme`/SCSS compiles to a cache then ships as a
+FormatDependency under `site_libs/bootstrap|quarto-html` with hrefs built
+from the input-relative lib dir; document `resources:`/`project.resources`
+mirror project-relative paths, no hrefs. Four placement policies for four
+consumption models.
+
+## Evidence pass 2: q2 boundary audit
+
+Per-key status at `main` @ `10d86829` (file:line cites in the agent record;
+load-bearing ones inline):
+
+| key | q2 today |
+|---|---|
+| `format.html.css` | linked verbatim (`extract_css_from_meta`, `template.rs:928`); never copied; only other references are the two extension pattern tables. **On revealjs, user css is dropped entirely** — the scaffold only takes artifact URLs (`revealjs/assemble.rs:369-410`, `apply_template.rs:302-306`), so not even a broken `<link>` is emitted. |
+| `theme` | compiled to Project-scoped artifact `css:theme:<fp>` (`compile_theme_css.rs:707-730`); per-page URL via resolver (`apply_template.rs:166` → `html_url_for`); flushed to `site_libs` (website) or per-page `<stem>_files` (default/book). Healthy. |
+| `include-in-header`/`-before-body`/`-after-body` | inlined by `IncludeResolveStage` into `rendered.includes.*` — Q1 parity. Raw `<script>`/`<link>` written inside them is emitted byte-for-byte (same as Q1; authors own those paths). |
+| `format-resources` | **accepted but never consumed** — only the two pattern tables mention it; silently inert, no diagnostic. (Q1 flattens basename-only next to output for LaTeX/Typst-style consumers.) Follow-up strand. |
+| user js | no `scripts:` metadata key in Q1 either; user js arrives via includes. Parity — no gap beyond includes being verbatim. |
+| favicon / navbar logo / footer images | copied (post-render hooks, website-only) + separately href-resolved per page by their transforms (`apply_favicon` → `page_url_for`; navbar logo → `resolve_root_relative_resource_href`, `navbar_render.rs:121`). |
+| `project.resources` / doc `resources` | glob → mirror copy `copy_resources_to_output_dir` (`project_resources.rs:1093`), all project types, post-render, copy-only. Healthy. |
+| `brand` | styling rides the theme artifact; brand files ride favicon/navbar paths. No separate gap. |
+
+**Structural facts that constrain the fix:**
+
+- **Books don't share `website_post_render.rs`.** `ProjectKind::Book |
+  Manuscript → DefaultProjectType` (`orchestrator.rs:517-522`), which
+  inherits the default no-op-ish `post_render`. A website-only hook leaves
+  books broken. Cross-type channels: (i) per-page `ResourceCopyIntent`
+  (`render.rs:186`, flushed in both `render_to_file.rs:413` and
+  `pass2_renderer.rs:896,1180` — the `title_banner.rs:139-150` precedent,
+  which does copy-intent + href in one transform), or (ii) Project-scoped
+  artifacts.
+- **The artifact route** would give copy + per-page href for free
+  (`collect_artifact_urls` picks up every `css:` key), but relocates
+  everything under `site_libs/` — diverging from Q1's mirror layout for
+  project-root css, and key collisions demand a fingerprint in the key.
+- **`resolve_root_relative_resource_href`** (`navigation_href.rs:467`) is
+  the purpose-built call for config-declared asset hrefs (external-URL
+  passthrough, query/fragment handling, project-root anchoring).
+- **Layer provenance only exists at merge time.** A document-front-matter
+  `css:` entry is authored document-relative; a `_quarto.yml` entry is
+  project-relative. After the merge flattens layers, template-time code
+  cannot tell them apart. Q1 solves this by rebasing per layer inside the
+  merge (each `toInputRelativePaths` call gets the right base dir). q2's
+  equivalent seam is `adjust_paths_to_document_dir`, already applied per
+  layer (`metadata_merge.rs:256,266`) — and `css: !path styles.css`
+  already rebases today (test at `project/mod.rs:2795-2831`).
+
+## Synthesis: proposed mechanism (pending user confirmation)
+
+Q1's evidence cuts both ways on the earlier question 2: Q1 itself uses
+merge-time string rebasing (mechanism (a)) for `css`, but only because its
+pandoc-cwd constraint forces every path to be input-relative; the
+copy side is a separate mirror. q2 has no such constraint, and the user's
+concern (input tree won't always mirror output tree) stands. But pure
+template-time resolution (mechanism (b)) loses layer provenance.
+
+Proposed hybrid — **(a)'s marking, (b)'s emission**:
+
+1. **Merge time (provenance-aware):** existence-driven marking of
+   `format.*.css` entries as Path-kind per layer — normalizing every entry
+   to a *document-dir-relative* value exactly as the existing
+   `adjust_paths_to_document_dir` machinery already does for `!path` and
+   extension-fragment values. Near-zero new code: extend the marking that
+   extension fragments already get to the project's own config layer (and
+   directory metadata), scoped to the audited key list.
+2. **Render time (output-aware):** a transform (Navigation/Finalization
+   phase, all HTML formats) that walks the merged `css` list and, per
+   entry: skips external URLs; resolves to a project-root-relative source;
+   chooses the output location — **mirror of the project-relative path**,
+   except entries under `_extensions/` relocate to
+   `<lib_dir>/quarto-contrib/quarto-project/<rest>` (Q1 parity, and the
+   only way to avoid shipping `_extensions/` paths); pushes a
+   `ResourceCopyIntent` (works for every project type); rewrites the
+   entry to the per-page href via `resolve_root_relative_resource_href` /
+   `page_url_for`; emits the missing-file Q-code when the source doesn't
+   exist. `extract_css_from_meta` then emits pre-resolved values unchanged.
+
+This keeps Q1's output layout (`_site/styles.css`;
+`site_libs/quarto-contrib/quarto-project/acme/widget/widget.css`), works
+for websites *and* books/default projects (copy-intent channel), and keeps
+the resolver as the single source of href truth so a future
+input≠output-tree world only touches step 2.
+
+For books/single-doc, `lib_dir` is empty — the relocation target falls back
+to the resolver's Project scope root (`<stem>_files/`), matching where
+theme css already lands there (Q1 analog: `<stem>_files/libs/`).
+
 ## Proposed phases (draft)
 
-Skeleton only — actual phase contents wait on the design discussion.
-
-- **Phase 0 — Test plan (TDD).** End-to-end website render tests driving the
-  real project pipeline: (a) `_site/styles.css` exists after render;
-  (b) extension-path css exists at the decided output location; (c) deep
-  page's `<link href>` is depth-correct; (d) missing declared css warns
-  (and root page still renders); (e) external URL entries pass through
-  untouched. Verify each fails at HEAD first.
-- **Phase 1 — Copy.** `copy_format_css` in `website_post_render.rs` on the
-  `copy_asset_file` seam; iterate merged `format.html.css` entries; skip
-  external URLs; warn on missing source (favicon parity).
-- **Phase 2 — Rebase.** Per-page depth-correct hrefs via the chosen
-  mechanism (design question 2).
-- **Phase 3 — Diagnostic.** Warning for missing declared css; decide plain
-  warning vs. Q-code (a Q-code requires the docs page in the same commit —
-  `error-docs-page-missing` lint).
-- **Phase 4 — End-to-end verification + docs.** Render the fixture through
-  `cargo run --bin q2 -- render`, inspect output, re-check the Connect docs
-  repro; user-facing docs if any behavior is documented.
-
-## Open design questions for the user
-
-1. **Output layout for css under `_extensions/`.** Q1 relocates
-   extension-owned css to
-   `site_libs/quarto-contrib/quarto-project/<org>/<ext>/…` and rewrites the
-   href accordingly. The simpler alternative is to copy preserving the
-   project-relative path (`_site/_extensions/acme/widget/widget.css`) and
-   emit the rebased href to that. Q1 parity, or the simpler layout? (Q1
-   avoids copying `_extensions/` into output wholesale; do we care about
-   that convention here?)
-2. **Rebase mechanism.** Two candidates with in-tree precedent:
-   (a) mark project-config `format.*.css` entries as `ConfigValueKind::Path`
-   (existence-driven, like extension fragments) and let the existing
-   `adjust_paths_to_document_dir` merge machinery emit document-relative
-   values — near-zero new code, but couples href shape to the input tree
-   mirroring the output tree; or (b) resolve at template/transform time via
-   the per-page `ResourceResolverContext`, like the favicon and theme
-   bundle — more explicit, and the same seam a later `site_libs` relocation
-   (question 1) would need anyway. Which?
-3. **Scope beyond `css`.** The same boundary presumably affects sibling
-   config-declared assets (`include-in-header` files are inlined so likely
-   fine, but what about `format-resources`, user `js`/`scripts` entries, and
-   document-level `css:` declared in a subdirectory page's front matter —
-   resolved against the document dir?). Fix `css` only here and file
-   follow-ups, or audit the boundary in this strand?
-4. **Diagnostic shape.** Favicon uses a plain `DiagnosticMessage::warning`.
-   Same here, or mint a Q-code (requires `docs/errors/` page + catalog entry
-   in the same commit)?
-5. **Preview parity.** `website_post_render` hooks are native-only. Does the
-   in-browser preview / `q2 preview` serve declared css from the source tree
-   already (VFS), or does preview need its own leg? (Fine to answer "verify
-   during Phase 4 and file a follow-up if broken.")
+Refined after the two evidence passes; still pending user sign-off on the
+follow-up questions below.
+
+- **Phase 0 — Test plan (TDD).** End-to-end tests driving the real render
+  path (`render_document_to_file` / project orchestrator, per the
+  end-to-end policy): (a) website render writes `_site/styles.css`;
+  (b) `_extensions/`-owned entry lands at the relocation target and its
+  href points there; (c) deep page's `<link href>` is depth-correct;
+  (d) document-front-matter `css:` in a subdirectory resolves against the
+  document dir, is copied, and links correctly; (e) missing declared css
+  emits the new Q-code and the render completes; (f) external URL entries
+  pass through untouched; (g) book/default-project render copies the css
+  (copy-intent channel, no website hook); (h) `url()`-referenced assets:
+  decide + pin behavior (question F3). Each verified failing at HEAD first.
+- **Phase 1 — Merge-time marking.** Extend existence-driven Path-kind
+  marking to the project's own config layer (and directory metadata) for
+  `format.*.css`, so entries normalize per layer like `!path` values
+  already do (layer provenance).
+- **Phase 2 — Render-time transform.** New transform (all HTML formats):
+  per css entry — external-URL passthrough, output-location choice (mirror
+  of the project-relative path; `_extensions/**` relocates to
+  `<lib_dir>/quarto-contrib/quarto-project/**`), `ResourceCopyIntent`,
+  per-page href rewrite via the resolver, Q-code on missing source. Wire
+  the emitted list into revealjs's `css_urls` too so user css stops being
+  dropped there (question F2).
+- **Phase 3 — Q-code + docs page.** New catalog entry + `docs/errors/`
+  page in the same commit (`error-docs-page-missing` lint enforces).
+- **Phase 4 — End-to-end verification + follow-ups.** Render the
+  investigation fixture and the Connect docs repro through the real
+  binary, inspect output; verify `q2 preview` behavior and file the
+  preview follow-up strand if broken; file the `format-resources` strand;
+  user-facing docs.
+
+## Design decisions (user, 2026-08-14)
+
+Answers to the questions below, recorded before the quarto-cli evidence pass:
+
+1. **Output layout:** never `cp -r _extensions/` into output (authors ship
+   README.md etc. that don't belong). Individual declared assets may be
+   copied "along the same path"; study `external-sources/quarto-cli` for
+   the rationale behind Q1's `site_libs/quarto-contrib/quarto-project/…`
+   relocation before settling the exact layout.
+2. **Rebase mechanism:** leaning (b) (per-page `ResourceResolverContext`),
+   because q2 will not always be able to replicate input-tree paths in the
+   output tree. Not held strongly — check quarto-cli for evidence either
+   way; follow-up question allowed.
+3. **Scope:** audit the whole config-declared-asset boundary in this
+   strand, not just `css`.
+4. **Diagnostic:** mint a new Q-code (project direction: remove plain
+   warnings). Requires catalog entry + `docs/errors/` page in the same
+   commit (`error-docs-page-missing` lint).
+5. **Preview:** this strand targets render parity; verify preview behavior
+   during Phase 4 and file a follow-up strand if broken.
+
+## Resolved by the evidence passes
+
+(The original five questions are preserved with the user's answers in
+"Design decisions" above. The evidence passes resolved their open parts:)
+
+- **Layout:** Q1 parity — mirror project-relative paths; `_extensions/**`
+  relocates to `<lib_dir>/quarto-contrib/quarto-project/**`. Q1's rationale
+  (underscore dirs are systematically non-output; relocation ships only the
+  individually-referenced files; `quarto-contrib` is the reserved,
+  freezer-protected namespace) matches the user's constraint exactly.
+- **Mechanism:** hybrid proposed — merge-time layer-aware Path marking +
+  render-time resolver-driven copy/href transform (see Synthesis). Pending
+  F1.
+- **Scope:** boundary audited (table in Evidence pass 2). Real gaps found:
+  revealjs drops user css entirely (F2); `format-resources` accepted but
+  inert (F4).
+- **Diagnostic:** new Q-code (Phase 3).
+- **Preview:** verify in Phase 4; follow-up strand if broken.
+
+## Follow-up questions for the user
+
+- **F1 (mechanism sign-off).** The hybrid in "Synthesis": merge-time
+  Path-kind marking for layer provenance (Q1 performs its rebase at the
+  same point, per layer) + a render-time transform that owns copy intent
+  and per-page href through the resolver. OK to proceed on that shape?
+- **F2 (revealjs).** User `css:` on revealjs is currently dropped entirely
+  (worse than the website bug — not even a broken `<link>` is emitted).
+  Fix it in this strand (Phase 2's transform naturally covers it) or file
+  separately to keep this strand website-focused?
+- **F3 (css `url()` refs).** Q1's `copyResourceFile` chases `url()` /
+  `@import` references inside copied css and copies those files too
+  (`project-resources.ts:110-138`). Real-world css (including the Connect
+  docs port) may rely on this for background images and fonts. In scope
+  here, or an explicit follow-up strand with a documented limitation?
+- **F4 (`format-resources`).** Confirm filing it as its own strand
+  (`discovered-from` this one), suggested p2: it silently no-ops today,
+  and its Q1 consumers are LaTeX/Typst-style sibling-file formats.
 
 ## Risks / tradeoffs (draft)
 
-- **Book projects** likely share the symptom (same template path); fixing
-  only the website post-render hook would leave books broken. Worth checking
-  where books' post-render lives before committing to the seam.
-- Choosing rebase mechanism (a) silently changes the merged metadata value
-  shape (`Scalar` → `Path`) for a user-visible key; downstream readers of
-  `css` metadata (Lua filters, template contexts) would observe rewritten
-  values. Mechanism (b) keeps metadata untouched.
+- **Books:** confirmed — `ProjectKind::Book → DefaultProjectType` with no
+  post-render of its own, so the fix must use a cross-type channel
+  (`ResourceCopyIntent`), not `website_post_render.rs`. Phase 0(g) pins
+  this.
+- Merge-time Path marking changes the merged metadata value shape
+  (`Scalar` → `Path`) for a user-visible key; downstream readers (Lua
+  filters, template contexts) observe normalized values. Q1 mutates
+  metadata the same way (`toInputRelativePaths`), so filter-visible
+  rewritten paths are Q1-compatible behavior — but worth stating in docs.
+- The relocation choice hard-codes Q1's `quarto-contrib/quarto-project`
+  literal into q2 output layout; freeze does not exist in q2 yet, so the
+  freezer-protection rationale is speculative here — we adopt the layout
+  for output parity, not for freezer semantics.
 - The design strand bd-root-relative-paths-design-fc5pvkcv is still
   in_progress; its remaining case C (raw HTML) is independent, but any
   decision here should cite its Decision 4/5 vocabulary (leading `/` =

From e0316c6525907042159c7db3458f21a5e8215b0f Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Fri, 14 Aug 2026 16:26:46 -0500
Subject: [PATCH 3/6] bd-format-css-not-copied-crn3bjdz: design settled
 (F1-F4), follow-ups filed

F1 hybrid mechanism approved (merge-time Path marking + render-time
resolver transform); F2 revealjs user-css drop fixed in-strand; F3
css url() chasing filed as bd-dxp854dw (p2); F4 format-resources
no-op filed as bd-ptb0v2lk (p2). Ready to implement on go-ahead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-14-format-css-not-copied.md | 37 +++++++++----------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/claude-notes/plans/2026-08-14-format-css-not-copied.md b/claude-notes/plans/2026-08-14-format-css-not-copied.md
index 5fe82bc89..08a5f489a 100644
--- a/claude-notes/plans/2026-08-14-format-css-not-copied.md
+++ b/claude-notes/plans/2026-08-14-format-css-not-copied.md
@@ -3,7 +3,9 @@
 **Date:** 2026-08-14
 **Braid:** bd-format-css-not-copied-crn3bjdz (bug, p1, label `websites`)
 **Checkout:** main checkout, branch `main` @ `10d86829` (investigation only — no worktree/branch created)
-**Status:** Investigation — pending design alignment with user. **Do not start implementation until the user gives the go-ahead.**
+**Status:** Investigation + design alignment complete (2026-08-14, F1–F4
+settled — see "Settled follow-ups"). **Ready to implement on user
+go-ahead; implementation has not started.**
 
 ## Triage verdict
 
@@ -353,24 +355,21 @@ Answers to the questions below, recorded before the quarto-cli evidence pass:
 - **Diagnostic:** new Q-code (Phase 3).
 - **Preview:** verify in Phase 4; follow-up strand if broken.
 
-## Follow-up questions for the user
-
-- **F1 (mechanism sign-off).** The hybrid in "Synthesis": merge-time
-  Path-kind marking for layer provenance (Q1 performs its rebase at the
-  same point, per layer) + a render-time transform that owns copy intent
-  and per-page href through the resolver. OK to proceed on that shape?
-- **F2 (revealjs).** User `css:` on revealjs is currently dropped entirely
-  (worse than the website bug — not even a broken `<link>` is emitted).
-  Fix it in this strand (Phase 2's transform naturally covers it) or file
-  separately to keep this strand website-focused?
-- **F3 (css `url()` refs).** Q1's `copyResourceFile` chases `url()` /
-  `@import` references inside copied css and copies those files too
-  (`project-resources.ts:110-138`). Real-world css (including the Connect
-  docs port) may rely on this for background images and fonts. In scope
-  here, or an explicit follow-up strand with a documented limitation?
-- **F4 (`format-resources`).** Confirm filing it as its own strand
-  (`discovered-from` this one), suggested p2: it silently no-ops today,
-  and its Q1 consumers are LaTeX/Typst-style sibling-file formats.
+## Settled follow-ups (user, 2026-08-14)
+
+- **F1 — mechanism: hybrid approved.** Merge-time per-layer Path-kind
+  marking (normalization + provenance) + render-time transform owning
+  `ResourceCopyIntent` and per-page hrefs via the resolver.
+- **F2 — revealjs: in this strand.** Phase 2's transform wires the
+  resolved css list into revealjs's `css_urls`, ending the silent drop.
+- **F3 — css `url()`/`@import` chasing: follow-up strand.** Filed as
+  **bd-dxp854dw** (task, p2, discovered-from this strand). Copied user css
+  ships as-is; the limitation gets documented. (Evidence: Connect docs css
+  uses only `data:` URIs in `url()` — verified by grep — so the motivating
+  case is unaffected.)
+- **F4 — `format-resources`: filed as bd-ptb0v2lk** (bug, p2,
+  discovered-from this strand): silent no-op today; minimum fix is a
+  diagnostic, full fix is Q1's basename-flatten copy.
 
 ## Risks / tradeoffs (draft)
 

From 37758160e40fd43196d99de31b73c083366b3535 Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Fri, 14 Aug 2026 16:55:12 -0500
Subject: [PATCH 4/6] Implement format.html.css copy + per-page rebase
 (bd-format-css-not-copied-crn3bjdz)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User-declared stylesheets (format.html.css / document css:) are now
copied into the output tree and linked with depth-correct per-page
hrefs, Q1-parity:

- project-relative paths mirror into the output (_site/styles.css);
- _extensions/** entries relocate to
  <lib_dir>/quarto-contrib/quarto-project/** so the _extensions tree
  never ships (manifests, Lua sources, READMEs stay out);
- document front-matter css: resolves against the document's own
  directory; a leading / anchors at the project root;
- external URLs pass through verbatim;
- revealjs decks now link user css (previously dropped entirely);
- missing files warn with new code Q-5-29 (catalog + docs page):
  once per project render for _quarto.yml entries, per document for
  front-matter entries; the broken link is still emitted.

Mechanism (per the plan's settled design): existence-driven per-layer
Path-kind marking in MetadataMergeStage (project/format_css.rs)
+ a Normalization-phase FormatCssTransform that pushes
ResourceCopyIntents and rewrites entries to resolver-computed hrefs.
Works for websites, default projects/books, and single-doc renders;
VFS/preview mode deliberately untouched (Phase 4 follow-up).

Snapshot note: no .snap files changed. One smoke-all fixture
expectation updated (extensions/format-with-theme): bundled extension
css now links at its relocated quarto-contrib path instead of the
in-source _extensions path — and is actually copied, so it survives
a separate output-dir.

Tests: 9 new end-to-end integration tests (format_css.rs, written
first and verified failing at HEAD), 6 unit tests; full workspace
suite green (12182 passed).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-14-format-css-not-copied.md |  98 +++-
 crates/quarto-core/src/pipeline.rs            |   6 +
 crates/quarto-core/src/project/format_css.rs  | 352 +++++++++++++++
 crates/quarto-core/src/project/mod.rs         |   1 +
 .../quarto-core/src/project/orchestrator.rs   |   9 +
 .../src/stage/stages/apply_template.rs        |   8 +-
 .../src/stage/stages/metadata_merge.rs        |  51 ++-
 .../quarto-core/src/transforms/format_css.rs  | 223 +++++++++
 crates/quarto-core/src/transforms/mod.rs      |   3 +
 .../tests/integration/format_css.rs           | 427 ++++++++++++++++++
 crates/quarto-core/tests/integration/main.rs  |   1 +
 .../quarto-error-catalog/error_catalog.json   |   7 +
 .../extensions/format-with-theme/test.qmd     |   8 +-
 docs/errors/project/Q-5-29.qmd                |  63 +++
 14 files changed, 1247 insertions(+), 10 deletions(-)
 create mode 100644 crates/quarto-core/src/project/format_css.rs
 create mode 100644 crates/quarto-core/src/transforms/format_css.rs
 create mode 100644 crates/quarto-core/tests/integration/format_css.rs
 create mode 100644 docs/errors/project/Q-5-29.qmd

diff --git a/claude-notes/plans/2026-08-14-format-css-not-copied.md b/claude-notes/plans/2026-08-14-format-css-not-copied.md
index 08a5f489a..17f4119eb 100644
--- a/claude-notes/plans/2026-08-14-format-css-not-copied.md
+++ b/claude-notes/plans/2026-08-14-format-css-not-copied.md
@@ -3,9 +3,57 @@
 **Date:** 2026-08-14
 **Braid:** bd-format-css-not-copied-crn3bjdz (bug, p1, label `websites`)
 **Checkout:** main checkout, branch `main` @ `10d86829` (investigation only — no worktree/branch created)
-**Status:** Investigation + design alignment complete (2026-08-14, F1–F4
-settled — see "Settled follow-ups"). **Ready to implement on user
-go-ahead; implementation has not started.**
+**Status:** Implementation in progress on branch
+`braid/bd-format-css-not-copied-crn3bjdz` (Phases 0–3 complete, full
+workspace suite green 12182/12182; Phase 4 verification underway — see
+"Phase 4 evidence").
+
+## Phase 4 evidence (end-to-end, real binary)
+
+Run 2026-08-14 on the implementation branch:
+
+```
+cargo run --bin q2 -- render claude-notes/plans/format-css-not-copied-investigation/repro
+# → "Rendered 2 of 2 files", exit 0
+```
+
+Output inspected directly (matches Q1's expected table from the repro
+README exactly):
+
+- `_site/styles.css` exists (marker property `--repro-project-css` present);
+- `_site/site_libs/quarto-contrib/quarto-project/acme/widget/widget.css`
+  exists (marker `--repro-extension-css` present); no `_site/_extensions/`;
+- `index.html`: `href="styles.css"`,
+  `href="site_libs/quarto-contrib/quarto-project/acme/widget/widget.css"`,
+  linked after the theme bundle;
+- `deep/deeper/index.html`: `href="../../styles.css"`,
+  `href="../../site_libs/quarto-contrib/quarto-project/acme/widget/widget.css"`.
+
+Also verified through the binary: single-doc `fancyfmt-html` extension
+render relocates+copies bundled css to
+`test_files/quarto-contrib/quarto-project/fancyfmt/fmt-style.css` (its
+smoke-all fixture now pins this — previously the link only worked because
+output landed beside the source tree).
+
+## Implementation shape (as landed)
+
+- **Marking** (`crates/quarto-core/src/project/format_css.rs`):
+  `mark_css_path_values` — existence-driven, per layer, called from
+  `MetadataMergeStage` for the project layer (after the `!path`
+  adjustment; diagnostics dropped there), directory-metadata layers, and
+  the document layer (diagnostics pushed per document).
+  `missing_project_css_diagnostics` runs once per project render from
+  `ProjectPipeline::run` into `project_diagnostics` (Q-5-29).
+- **Transform** (`crates/quarto-core/src/transforms/format_css.rs`):
+  `FormatCssTransform` (Normalization phase, self-gated to HTML-family,
+  no-op in VFS mode) — consumes only marked Path entries; mirrors
+  project-relative paths; relocates `_extensions/**` to
+  `quarto-contrib/quarto-project/**` via `ArtifactScope::Project`
+  resolver queries; pushes `ResourceCopyIntent`s (skipping src==dest);
+  rewrites entries to per-page hrefs. Never diagnoses.
+- **Revealjs**: `apply_template.rs` reveal branch appends
+  `user_css_urls(&metadata)` after the vendored deck assets.
+- **Q-5-29**: catalog entry + `docs/errors/project/Q-5-29.qmd`.
 
 ## Triage verdict
 
@@ -280,6 +328,50 @@ For books/single-doc, `lib_dir` is empty — the relocation target falls back
 to the resolver's Project scope root (`<stem>_files/`), matching where
 theme css already lands there (Q1 analog: `<stem>_files/libs/`).
 
+## Work items
+
+Implementation runs on branch `braid/bd-format-css-not-copied-crn3bjdz`
+(remote will be `bugfix/bd-format-css-not-copied-crn3bjdz`), branched from
+`main` @ `10d86829` with the investigation commits.
+
+### Phase 0 — failing tests first
+
+- [x] Integration: website render copies project-root css to `_site/styles.css`
+- [x] Integration: hrefs depth-correct (`styles.css` at root, `../../styles.css` two deep)
+- [x] Integration: `_extensions/**` css relocated to `site_libs/quarto-contrib/quarto-project/**`, hrefs point there
+- [x] Integration: document front-matter `css:` in a subdirectory resolves against the document dir (copied + linked)
+- [x] Integration: missing declared css → Q-code diagnostic, link still emitted, render completes
+- [x] Integration: external URL entries pass through verbatim, no copy, no diagnostic
+- [x] Integration: default-project (DefaultProjectType — books' dispatch) render copies css + correct hrefs
+- [x] Integration: revealjs single-doc render links user `css:` (currently dropped)
+- [x] All of the above verified failing at HEAD
+
+### Phase 1 — merge-time marking
+
+- [x] Unit tests: project-config `css` scalar/array/inlines marked Path-kind when file exists; untouched otherwise
+- [x] Mark `format.*.css` in the project's own config layer (existence-driven, base = project dir)
+- [x] Same for directory metadata (`_metadata.yml`) and document front matter layers as applicable
+
+### Phase 2 — render-time transform
+
+- [x] New transform: copy intents + per-page hrefs via resolver; `_extensions/**` relocation; external-URL passthrough
+- [x] Missing-file Q-code emission
+- [x] Revealjs: user css list appended to `css_urls` in the apply-template reveal branch
+- [x] Pipeline wiring + phase-ordering test still green
+
+### Phase 3 — Q-code + docs
+
+- [x] Catalog entry in `quarto-error-catalog/error_catalog.json`
+- [x] `docs/errors/<subsystem>/<code>.qmd` page (same commit; `error-docs-page-missing` lint)
+
+### Phase 4 — end-to-end verification + follow-ups
+
+- [x] `cargo run --bin q2 -- render` on the investigation fixture; inspect output (record snippet in plan)
+- [ ] Re-check the Connect docs repro
+- [ ] Verify `q2 preview` behavior; file preview follow-up strand if broken
+- [ ] Full `cargo xtask verify` green
+- [ ] User-facing docs if applicable
+
 ## Proposed phases (draft)
 
 Refined after the two evidence passes; still pending user sign-off on the
diff --git a/crates/quarto-core/src/pipeline.rs b/crates/quarto-core/src/pipeline.rs
index 72067bca7..8f56b45fa 100644
--- a/crates/quarto-core/src/pipeline.rs
+++ b/crates/quarto-core/src/pipeline.rs
@@ -1284,6 +1284,12 @@ pub fn build_transform_pipeline(
     pipeline.push(Box::new(WebsiteFaviconTransform::new()));
     pipeline.push(Box::new(WebsiteBootstrapIconsTransform::new()));
     pipeline.push(Box::new(WebsiteCanonicalUrlTransform::new()));
+    // User-declared stylesheets (bd-format-css-not-copied-crn3bjdz):
+    // copy `css:` files into the output tree and rewrite the entries
+    // to per-page hrefs. Not website-scoped — default projects (and
+    // books, which ride the same dispatch) and single-doc renders get
+    // the same treatment. Self-gates to HTML-family formats.
+    pipeline.push(Box::new(crate::transforms::FormatCssTransform::new()));
     // Draft marking (bd-draft-banner-missing-hgx1gkqm). Not website-scoped
     // — a standalone `draft: true` document gets the banner too — but it
     // belongs with the metadata producers above: it only writes
diff --git a/crates/quarto-core/src/project/format_css.rs b/crates/quarto-core/src/project/format_css.rs
new file mode 100644
index 000000000..e8596394c
--- /dev/null
+++ b/crates/quarto-core/src/project/format_css.rs
@@ -0,0 +1,352 @@
+/*
+ * project/format_css.rs
+ * Copyright (c) 2026 Posit, PBC
+ *
+ * User-declared stylesheet (`css:` / `format.html.css`) path marking
+ * and the Q-5-29 missing-file diagnostic.
+ * bd-format-css-not-copied-crn3bjdz.
+ */
+
+//! Merge-time marking of user-declared stylesheet paths.
+//!
+//! A `css:` entry is authored relative to the file that declares it:
+//! `_quarto.yml` entries are project-root-relative, `_metadata.yml`
+//! entries are relative to that file's directory, and document
+//! front-matter entries are relative to the document. After the
+//! metadata merge flattens these layers, that provenance is gone — so
+//! each layer's entries are normalized *during* the merge, while the
+//! layer's base directory is still known ([`mark_css_path_values`]).
+//!
+//! Marking is existence-driven, mirroring the extension-fragment
+//! machinery (`FRAGMENT_PATH_PATTERNS`) and Q1's
+//! `toInputRelativePaths`: a string that names an existing file
+//! becomes a [`ConfigValueKind::Path`] holding the equivalent
+//! document-relative path; external URLs and strings that name no
+//! file pass through untouched. The downstream
+//! [`FormatCssTransform`](crate::transforms::FormatCssTransform)
+//! consumes only marked (`Path`-kind) entries — copy intents and
+//! per-page hrefs — and never diagnoses; missing files are diagnosed
+//! here, at the declaration site, so a project-wide mistake warns
+//! once per declaring layer instead of once per rendered page:
+//!
+//! - project config: [`missing_project_css_diagnostics`], called once
+//!   per project render by the orchestrator;
+//! - directory metadata and document front matter: the diagnostics
+//!   returned by [`mark_css_path_values`], pushed into the declaring
+//!   document's own render diagnostics.
+
+use std::path::{Path, PathBuf};
+
+use quarto_config::resolve_format_config;
+use quarto_error_reporting::{DiagnosticMessage, DiagnosticMessageBuilder};
+use quarto_pandoc_types::ConfigValue;
+use quarto_pandoc_types::config_value::ConfigValueKind;
+use quarto_system_runtime::SystemRuntime;
+
+use crate::project::ProjectContext;
+
+/// Apply `f` to a `css:` value's string-bearing leaves: the scalar
+/// forms directly, or each item of the array form.
+fn for_each_css_entry_mut(css: &mut ConfigValue, mut f: impl FnMut(&mut ConfigValue)) {
+    match &mut css.value {
+        ConfigValueKind::Array(items) => {
+            for item in items {
+                f(item);
+            }
+        }
+        _ => f(css),
+    }
+}
+
+/// Immutable counterpart of [`for_each_css_entry_mut`].
+fn for_each_css_entry(css: &ConfigValue, mut f: impl FnMut(&ConfigValue)) {
+    match &css.value {
+        ConfigValueKind::Array(items) => {
+            for item in items {
+                f(item);
+            }
+        }
+        _ => f(css),
+    }
+}
+
+/// Resolve a declared css string against its layer.
+///
+/// A leading `/` means site-root-relative (Decision 4 of
+/// bd-root-relative-paths-design-fc5pvkcv), so it anchors at the
+/// project root regardless of which layer declared it; anything else
+/// anchors at the declaring layer's own base directory.
+fn candidate_path(declared: &str, layer_base: &Path, project_dir: &Path) -> PathBuf {
+    match declared.strip_prefix('/') {
+        Some(rest) => project_dir.join(rest),
+        None => layer_base.join(declared),
+    }
+}
+
+/// Mark existing user-declared stylesheets in one metadata layer as
+/// document-relative `Path` values.
+///
+/// `layer_base` is the directory the layer's relative paths are
+/// authored against (project root for `_quarto.yml`, the metadata
+/// file's directory for `_metadata.yml`, the document's directory for
+/// front matter). Entries that are already `Path`-kind (explicit
+/// `!path`, extension fragments) are left alone — the merge machinery
+/// already rebases those.
+///
+/// Returns a Q-5-29 warning for each entry that names no file. The
+/// caller decides whether to surface them: per-document layers push
+/// them into the document's diagnostics; the project layer drops them
+/// because [`missing_project_css_diagnostics`] reports the same
+/// entries once per project render instead of once per page.
+pub(crate) fn mark_css_path_values(
+    metadata: &mut ConfigValue,
+    layer_base: &Path,
+    project_dir: &Path,
+    document_dir: &Path,
+    runtime: &dyn SystemRuntime,
+) -> Vec<DiagnosticMessage> {
+    let mut diagnostics = Vec::new();
+    let Some(css) = metadata.get_mut("css") else {
+        return diagnostics;
+    };
+    for_each_css_entry_mut(css, |entry| {
+        if matches!(entry.value, ConfigValueKind::Path(_)) {
+            return;
+        }
+        let Some(declared) = entry.as_plain_text() else {
+            return;
+        };
+        if quarto_util::is_external_url(&declared) {
+            return;
+        }
+        let source = candidate_path(&declared, layer_base, project_dir);
+        if runtime.is_file(&source).unwrap_or(false) {
+            let doc_relative =
+                pathdiff::diff_paths(&source, document_dir).unwrap_or_else(|| source.clone());
+            entry.value = ConfigValueKind::Path(quarto_util::to_forward_slashes(&doc_relative));
+        } else {
+            diagnostics.push(missing_css_diagnostic(&declared, entry));
+        }
+    });
+    diagnostics
+}
+
+/// Build the Q-5-29 warning for a declared stylesheet whose file does
+/// not exist. The `<link>` is still emitted verbatim (a visibly
+/// broken stylesheet beats a silently absent one — the favicon
+/// posture), and nothing is copied.
+fn missing_css_diagnostic(declared: &str, entry: &ConfigValue) -> DiagnosticMessage {
+    DiagnosticMessageBuilder::warning(format!("`css` refers to missing file '{declared}'"))
+        .with_code("Q-5-29")
+        .with_location(entry.source_info.clone())
+        .problem(format!(
+            "The declared stylesheet `{declared}` does not exist, so it was \
+             not copied into the output. Every page linking it will request \
+             a file that is not there. The render continued without it."
+        ))
+        .add_hint(
+            "Check the path in the `css` entry (it is resolved relative to \
+             the file that declares it), or add the missing stylesheet.",
+        )
+        .build()
+}
+
+/// Project-render-level check of the project config's own `css`
+/// entries, run **once** by the orchestrator (so a `_quarto.yml`
+/// mistake does not warn once per rendered page).
+///
+/// Checks every non-URL entry — including explicit `!path` values,
+/// which the per-layer marking deliberately skips — against the
+/// project root.
+pub fn missing_project_css_diagnostics(
+    project: &ProjectContext,
+    base_format: &str,
+    runtime: &dyn SystemRuntime,
+) -> Vec<DiagnosticMessage> {
+    let mut diagnostics = Vec::new();
+    let Some(metadata) = project.config.metadata.as_ref() else {
+        return diagnostics;
+    };
+    let flattened = resolve_format_config(metadata, base_format);
+    let Some(css) = flattened.get("css") else {
+        return diagnostics;
+    };
+    for_each_css_entry(css, |entry| {
+        let Some(declared) = entry.as_plain_text() else {
+            return;
+        };
+        if quarto_util::is_external_url(&declared) {
+            return;
+        }
+        let source = candidate_path(&declared, &project.dir, &project.dir);
+        if !runtime.is_file(&source).unwrap_or(false) {
+            diagnostics.push(missing_css_diagnostic(&declared, entry));
+        }
+    });
+    diagnostics
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use quarto_pandoc_types::ConfigMapEntry;
+    use quarto_source_map::SourceInfo;
+    use quarto_system_runtime::NativeRuntime;
+
+    fn scalar(s: &str) -> ConfigValue {
+        ConfigValue::new_string(s, SourceInfo::for_test())
+    }
+
+    fn css_map(entries: Vec<ConfigValue>) -> ConfigValue {
+        let css = if entries.len() == 1 {
+            entries.into_iter().next().unwrap()
+        } else {
+            ConfigValue::new_array(entries, SourceInfo::for_test())
+        };
+        ConfigValue::new_map(
+            vec![ConfigMapEntry {
+                key: "css".to_string(),
+                key_source: SourceInfo::for_test(),
+                value: css,
+            }],
+            SourceInfo::for_test(),
+        )
+    }
+
+    /// Existing file → Path-kind, rebased project dir → document dir.
+    #[test]
+    fn marks_existing_file_document_relative() {
+        let temp = tempfile::TempDir::new().unwrap();
+        let project = temp.path().canonicalize().unwrap();
+        std::fs::write(project.join("styles.css"), "x").unwrap();
+        let doc_dir = project.join("deep/deeper");
+        std::fs::create_dir_all(&doc_dir).unwrap();
+
+        let mut meta = css_map(vec![scalar("styles.css")]);
+        let diags = mark_css_path_values(
+            &mut meta,
+            &project,
+            &project,
+            &doc_dir,
+            &NativeRuntime::new(),
+        );
+        assert!(diags.is_empty(), "existing file must not diagnose");
+        let css = meta.get("css").unwrap();
+        assert_eq!(
+            css.value,
+            ConfigValueKind::Path("../../styles.css".to_string()),
+            "expected Path kind rebased to the document dir"
+        );
+    }
+
+    /// Missing file → untouched value + one Q-5-29 naming the entry.
+    #[test]
+    fn missing_file_diagnoses_and_leaves_value() {
+        let temp = tempfile::TempDir::new().unwrap();
+        let project = temp.path().canonicalize().unwrap();
+
+        let mut meta = css_map(vec![scalar("nope.css")]);
+        let diags = mark_css_path_values(
+            &mut meta,
+            &project,
+            &project,
+            &project,
+            &NativeRuntime::new(),
+        );
+        assert_eq!(diags.len(), 1);
+        assert_eq!(diags[0].code.as_deref(), Some("Q-5-29"));
+        assert!(diags[0].title.contains("nope.css"));
+        let entry = meta.get("css").unwrap();
+        assert!(
+            matches!(entry.value, ConfigValueKind::Scalar(_)),
+            "missing entry must stay Scalar"
+        );
+        assert_eq!(
+            entry.as_plain_text().as_deref(),
+            Some("nope.css"),
+            "missing entry must stay verbatim"
+        );
+    }
+
+    /// Array form: each item marked independently; URL passthrough.
+    #[test]
+    fn array_marks_items_independently_and_skips_urls() {
+        let temp = tempfile::TempDir::new().unwrap();
+        let project = temp.path().canonicalize().unwrap();
+        std::fs::write(project.join("a.css"), "x").unwrap();
+
+        let mut meta = css_map(vec![
+            scalar("a.css"),
+            scalar("https://example.com/x.css"),
+            scalar("gone.css"),
+        ]);
+        let diags = mark_css_path_values(
+            &mut meta,
+            &project,
+            &project,
+            &project,
+            &NativeRuntime::new(),
+        );
+        assert_eq!(diags.len(), 1, "only the missing local file diagnoses");
+        assert!(diags[0].title.contains("gone.css"));
+        let items = meta.get("css").unwrap().as_array().unwrap();
+        assert_eq!(items[0].value, ConfigValueKind::Path("a.css".to_string()));
+        assert!(matches!(items[1].value, ConfigValueKind::Scalar(_)));
+        assert_eq!(
+            items[1].as_plain_text().as_deref(),
+            Some("https://example.com/x.css")
+        );
+        assert!(matches!(items[2].value, ConfigValueKind::Scalar(_)));
+        assert_eq!(items[2].as_plain_text().as_deref(), Some("gone.css"));
+    }
+
+    /// A leading `/` anchors at the project root even when the layer
+    /// base is a subdirectory (Decision 4: site-root-relative).
+    #[test]
+    fn rooted_entry_anchors_at_project_root() {
+        let temp = tempfile::TempDir::new().unwrap();
+        let project = temp.path().canonicalize().unwrap();
+        std::fs::write(project.join("styles.css"), "x").unwrap();
+        let doc_dir = project.join("deep");
+        std::fs::create_dir_all(&doc_dir).unwrap();
+
+        let mut meta = css_map(vec![scalar("/styles.css")]);
+        let diags = mark_css_path_values(
+            &mut meta,
+            &doc_dir, // layer base is the doc dir — must not be used
+            &project,
+            &doc_dir,
+            &NativeRuntime::new(),
+        );
+        assert!(diags.is_empty());
+        assert_eq!(
+            meta.get("css").unwrap().value,
+            ConfigValueKind::Path("../styles.css".to_string())
+        );
+    }
+
+    /// Explicit `!path` values are the merge machinery's business —
+    /// marking must not touch them.
+    #[test]
+    fn explicit_path_kind_left_alone() {
+        let temp = tempfile::TempDir::new().unwrap();
+        let project = temp.path().canonicalize().unwrap();
+
+        let mut meta = css_map(vec![ConfigValue::new_path(
+            "already/rebased.css".to_string(),
+            SourceInfo::for_test(),
+        )]);
+        let diags = mark_css_path_values(
+            &mut meta,
+            &project,
+            &project,
+            &project,
+            &NativeRuntime::new(),
+        );
+        assert!(diags.is_empty());
+        assert_eq!(
+            meta.get("css").unwrap().value,
+            ConfigValueKind::Path("already/rebased.css".to_string())
+        );
+    }
+}
diff --git a/crates/quarto-core/src/project/mod.rs b/crates/quarto-core/src/project/mod.rs
index c02ec0e2f..89e371047 100644
--- a/crates/quarto-core/src/project/mod.rs
+++ b/crates/quarto-core/src/project/mod.rs
@@ -28,6 +28,7 @@ pub mod cache_key;
 pub mod dependency_graph;
 pub mod discovery;
 pub mod environment;
+pub mod format_css;
 pub mod index;
 pub mod listing;
 pub mod orchestrator;
diff --git a/crates/quarto-core/src/project/orchestrator.rs b/crates/quarto-core/src/project/orchestrator.rs
index 9e5d89b23..033e1891a 100644
--- a/crates/quarto-core/src/project/orchestrator.rs
+++ b/crates/quarto-core/src/project/orchestrator.rs
@@ -962,6 +962,15 @@ impl<'a, R: Pass2Renderer> ProjectPipeline<'a, R> {
             &self.project.config.render_patterns,
             &self.project.files,
         ));
+        // Project-config `css:` entries naming missing files warn once
+        // per render here — not once per page in the merge, which is
+        // where document-layer `css:` mistakes are diagnosed instead
+        // (bd-format-css-not-copied-crn3bjdz).
+        initial_diagnostics.extend(crate::project::format_css::missing_project_css_diagnostics(
+            self.project,
+            self.format.identifier.as_str(),
+            self.runtime.as_ref(),
+        ));
 
         let (profiles, pass1_failures) = self.pass_one().await;
         let index = Arc::new(ProjectIndex::new(profiles));
diff --git a/crates/quarto-core/src/stage/stages/apply_template.rs b/crates/quarto-core/src/stage/stages/apply_template.rs
index f86c98348..ec4b730db 100644
--- a/crates/quarto-core/src/stage/stages/apply_template.rs
+++ b/crates/quarto-core/src/stage/stages/apply_template.rs
@@ -299,8 +299,14 @@ impl PipelineStage for ApplyTemplateStage {
                 // `css:revealjs:*` / `js:revealjs:*` artifacts; we collect just
                 // those (a reveal deck never wants the Bootstrap `css:theme:*`)
                 // and the resolver gives the right per-context URLs.
-                let reveal_css =
+                let mut reveal_css =
                     collect_artifact_urls(ctx, "css:revealjs:", self.config.resolver.as_ref());
+                // User-declared `css:` entries, already resolved to
+                // per-page hrefs by `FormatCssTransform`. Linked after
+                // the vendored deck assets so user rules win the
+                // cascade — previously they were dropped entirely
+                // (bd-format-css-not-copied-crn3bjdz).
+                reveal_css.extend(crate::transforms::user_css_urls(&metadata));
                 let reveal_js =
                     collect_artifact_urls(ctx, "js:revealjs:", self.config.resolver.as_ref());
                 let html = crate::revealjs::render_revealjs_document(
diff --git a/crates/quarto-core/src/stage/stages/metadata_merge.rs b/crates/quarto-core/src/stage/stages/metadata_merge.rs
index 77b107efd..cba9b4369 100644
--- a/crates/quarto-core/src/stage/stages/metadata_merge.rs
+++ b/crates/quarto-core/src/stage/stages/metadata_merge.rs
@@ -241,8 +241,10 @@ impl PipelineStage for MetadataMergeStage {
             ctx.format.identifier.as_str()
         };
         // target_format is the full format string (e.g., "acm-html") used
-        // to look up extension metadata.
-        let target_format = &ctx.format.target_format;
+        // to look up extension metadata. Cloned so `ctx` stays mutably
+        // borrowable for the css-marking diagnostics below.
+        let target_format = ctx.format.target_format.clone();
+        let target_format = target_format.as_str();
 
         // Layer 1: Project metadata (flattened for format)
         // Adjust !path values to be relative to document directory
@@ -254,6 +256,20 @@ impl PipelineStage for MetadataMergeStage {
         let project_layer = ctx.project.config.metadata.as_ref().map(|m| {
             let mut flattened = resolve_format_config(m, base_format);
             adjust_paths_to_document_dir(&mut flattened, &ctx.project.dir, &document_dir);
+            // Mark user-declared stylesheets that name existing files as
+            // document-relative Path values (bd-format-css-not-copied-crn3bjdz).
+            // Runs after the `!path` adjustment so explicit Path values are
+            // rebased exactly once. Missing-file diagnostics for the project
+            // layer are dropped here — the orchestrator reports them once per
+            // project render (`missing_project_css_diagnostics`), not once
+            // per page.
+            let _ = crate::project::format_css::mark_css_path_values(
+                &mut flattened,
+                &ctx.project.dir,
+                &ctx.project.dir,
+                &document_dir,
+                ctx.runtime.as_ref(),
+            );
             flattened
         });
 
@@ -335,13 +351,40 @@ impl PipelineStage for MetadataMergeStage {
             }
         }
 
+        // Directory-metadata and front-matter `css:` entries resolve
+        // against their declaring file's directory; marking normalizes
+        // existing files to document-relative Path values and returns a
+        // Q-5-29 per missing file, surfaced through this document's own
+        // diagnostics (bd-format-css-not-copied-crn3bjdz).
+        let mut css_diagnostics: Vec<quarto_error_reporting::DiagnosticMessage> = Vec::new();
         let dir_layers: Vec<_> = dir_layer_entries
             .into_iter()
-            .map(|(_, m)| resolve_format_config(&m, base_format))
+            .map(|(path, m)| {
+                let mut flattened = resolve_format_config(&m, base_format);
+                let layer_base = path
+                    .parent()
+                    .map_or_else(|| ctx.project.dir.clone(), |p| p.to_path_buf());
+                css_diagnostics.extend(crate::project::format_css::mark_css_path_values(
+                    &mut flattened,
+                    &layer_base,
+                    &ctx.project.dir,
+                    &document_dir,
+                    ctx.runtime.as_ref(),
+                ));
+                flattened
+            })
             .collect();
 
         // Layer 4: Document metadata (flattened for base format)
-        let doc_layer = resolve_format_config(&doc.ast.meta, base_format);
+        let mut doc_layer = resolve_format_config(&doc.ast.meta, base_format);
+        css_diagnostics.extend(crate::project::format_css::mark_css_path_values(
+            &mut doc_layer,
+            &document_dir,
+            &ctx.project.dir,
+            &document_dir,
+            ctx.runtime.as_ref(),
+        ));
+        ctx.add_diagnostics(css_diagnostics);
 
         // Layer 5: Runtime metadata (flattened for base format)
         let runtime_layer = runtime_meta_json
diff --git a/crates/quarto-core/src/transforms/format_css.rs b/crates/quarto-core/src/transforms/format_css.rs
new file mode 100644
index 000000000..3eddcb3ab
--- /dev/null
+++ b/crates/quarto-core/src/transforms/format_css.rs
@@ -0,0 +1,223 @@
+/*
+ * transforms/format_css.rs
+ * Copyright (c) 2026 Posit, PBC
+ *
+ * AST transform: copy user-declared stylesheets into the output tree
+ * and rewrite their `css:` metadata entries to per-page hrefs.
+ * bd-format-css-not-copied-crn3bjdz.
+ */
+
+//! Emit copy intents and per-page hrefs for user-declared stylesheets.
+//!
+//! The metadata merge already normalized `css:` entries that name
+//! existing files to document-relative [`ConfigValueKind::Path`]
+//! values ([`mark_css_path_values`]). This transform consumes exactly
+//! those marked entries; everything else (external URLs, missing
+//! files — already diagnosed at their declaration site) passes
+//! through verbatim, so a broken declaration still yields a visibly
+//! broken `<link>` rather than a silently absent one.
+//!
+//! Per marked entry:
+//!
+//! - the source is resolved to a project-root-relative path;
+//! - the output location mirrors that path (Q1 parity: `styles.css`
+//!   at the project root ships as `<output>/styles.css`) — except
+//!   files under `_extensions/`, which are relocated to
+//!   `quarto-contrib/quarto-project/<path>` under the project's lib
+//!   dir so the `_extensions/` tree itself never reaches the output
+//!   (it carries manifests, Lua sources, READMEs). This mirrors Q1's
+//!   `projectExtensionPathResolver`; the [`ArtifactScope::Project`]
+//!   resolver queries give the same layout on websites
+//!   (`site_libs/…`) and the per-page `<stem>_files/…` fallback
+//!   everywhere else;
+//! - a [`ResourceCopyIntent`] is pushed (skipped when source and
+//!   destination coincide, e.g. single-doc renders emitting next to
+//!   the source);
+//! - the metadata entry is rewritten to the page-relative href the
+//!   template will emit.
+//!
+//! The transform never diagnoses: see
+//! [`crate::project::format_css`] for the Q-5-29 emission sites.
+//!
+//! [`mark_css_path_values`]: crate::project::format_css
+//! [`ResourceCopyIntent`]: crate::render::ResourceCopyIntent
+
+use std::path::{Component, Path, PathBuf};
+
+use quarto_pandoc_types::ConfigValue;
+use quarto_pandoc_types::config_value::ConfigValueKind;
+use quarto_pandoc_types::pandoc::Pandoc;
+
+use crate::Result;
+use crate::artifact::ArtifactScope;
+use crate::render::{RenderContext, ResourceCopyIntent};
+use crate::transform::{AstTransform, TransformPhase};
+
+/// Prefix under the project root whose files are relocated rather
+/// than mirrored.
+const EXTENSIONS_PREFIX: &str = "_extensions/";
+
+/// Relocation target prefix (joined under the project lib dir by the
+/// `ArtifactScope::Project` resolver queries). `quarto-contrib` is
+/// Q1's reserved namespace for third-party content; `quarto-project`
+/// is its fixed "the project itself is the contributor" slot.
+const CONTRIB_PREFIX: &str = "quarto-contrib/quarto-project/";
+
+/// AST transform: copy user-declared stylesheets and rewrite their
+/// hrefs per page.
+pub struct FormatCssTransform;
+
+impl FormatCssTransform {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for FormatCssTransform {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait::async_trait(?Send)]
+impl AstTransform for FormatCssTransform {
+    fn name(&self) -> &str {
+        "format-css"
+    }
+
+    fn phase(&self) -> TransformPhase {
+        TransformPhase::Normalization
+    }
+
+    async fn transform(&self, ast: &mut Pandoc, ctx: &mut RenderContext) -> Result<()> {
+        if !ctx.format.is_html() {
+            return Ok(());
+        }
+        let Some(resolver) = ctx.resource_resolver.as_ref() else {
+            return Ok(());
+        };
+        // VFS-root mode (in-browser preview): the page is served from
+        // the VFS source tree, page depth is synthetic, and there is
+        // no on-disk output dir to copy into. Leave entries untouched
+        // — matching `ResourceCollectorTransform`'s posture. Preview
+        // behavior is verified separately (plan Phase 4).
+        if resolver.is_vfs_root_mode() {
+            return Ok(());
+        }
+        let document_dir = ctx
+            .document
+            .input
+            .parent()
+            .map_or_else(|| ctx.project.dir.clone(), Path::to_path_buf);
+
+        let mut copies: Vec<ResourceCopyIntent> = Vec::new();
+        let Some(css) = ast.meta.get_mut("css") else {
+            return Ok(());
+        };
+        let mut resolve = |entry: &mut ConfigValue| {
+            let ConfigValueKind::Path(doc_relative) = &entry.value else {
+                return;
+            };
+            let source = lexically_normalize(&document_dir.join(doc_relative));
+            let Some(project_relative) = pathdiff::diff_paths(&source, &ctx.project.dir) else {
+                return;
+            };
+            if project_relative
+                .components()
+                .next()
+                .is_some_and(|c| c == Component::ParentDir)
+            {
+                // Outside the project root: nothing we could ship.
+                // Q1's `copyResourceFile` refuses the same escape.
+                return;
+            }
+            let project_relative = quarto_util::to_forward_slashes(&project_relative);
+
+            let (href, dest) = match project_relative.strip_prefix(EXTENSIONS_PREFIX) {
+                Some(rest) => {
+                    let contrib = format!("{CONTRIB_PREFIX}{rest}");
+                    let contrib = Path::new(&contrib);
+                    (
+                        resolver.html_url_for(ArtifactScope::Project, contrib),
+                        resolver.on_disk_path_for(ArtifactScope::Project, contrib),
+                    )
+                }
+                None => {
+                    let href = resolver.page_url_for(&project_relative);
+                    let dest = lexically_normalize(&resolver.page_dir().join(&href));
+                    (href, dest)
+                }
+            };
+            if dest != source {
+                copies.push(ResourceCopyIntent {
+                    src: source,
+                    dest,
+                    origin: entry.source_info.clone(),
+                });
+            }
+            entry.value = ConfigValueKind::Path(href);
+        };
+        match &mut css.value {
+            ConfigValueKind::Array(items) => {
+                for item in items {
+                    resolve(item);
+                }
+            }
+            _ => resolve(css),
+        }
+        ctx.resource_copies.extend(copies);
+        Ok(())
+    }
+}
+
+/// Fold `.` and `..` components lexically (no filesystem access).
+/// Matches the normalization [`crate::output_sink::OutputSink`]
+/// applies to destinations, so src/dest comparisons agree with what
+/// the sink will actually write.
+fn lexically_normalize(path: &Path) -> PathBuf {
+    let mut out = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !out.pop() {
+                    out.push(Component::ParentDir.as_os_str());
+                }
+            }
+            other => out.push(other.as_os_str()),
+        }
+    }
+    out
+}
+
+/// Extract the final (post-transform) user css hrefs from merged
+/// metadata, in declaration order — the revealjs scaffold links these
+/// after its vendored assets, mirroring how the Bootstrap template
+/// appends user css after the theme. External URLs and unresolved
+/// (missing-file) entries come through verbatim.
+pub(crate) fn user_css_urls(metadata: &ConfigValue) -> Vec<String> {
+    let Some(css) = metadata.get("css") else {
+        return Vec::new();
+    };
+    match &css.value {
+        ConfigValueKind::Array(items) => items.iter().filter_map(|v| v.as_plain_text()).collect(),
+        _ => css.as_plain_text().map_or_else(Vec::new, |s| vec![s]),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lexical_normalize_folds_dotdot() {
+        assert_eq!(
+            lexically_normalize(Path::new("/a/b/c/../../styles.css")),
+            PathBuf::from("/a/styles.css")
+        );
+        assert_eq!(
+            lexically_normalize(Path::new("/a/./b.css")),
+            PathBuf::from("/a/b.css")
+        );
+    }
+}
diff --git a/crates/quarto-core/src/transforms/mod.rs b/crates/quarto-core/src/transforms/mod.rs
index 0a4df4523..9c6f8bacf 100644
--- a/crates/quarto-core/src/transforms/mod.rs
+++ b/crates/quarto-core/src/transforms/mod.rs
@@ -53,6 +53,7 @@ mod float_ref_target;
 mod footer_generate;
 mod footer_render;
 mod footnotes;
+mod format_css;
 mod link_rewrite;
 mod listing_generate;
 mod listing_render;
@@ -117,6 +118,8 @@ pub use float_ref_target::FloatRefTargetSugarTransform;
 pub use footer_generate::FooterGenerateTransform;
 pub use footer_render::FooterRenderTransform;
 pub use footnotes::FootnotesTransform;
+pub use format_css::FormatCssTransform;
+pub(crate) use format_css::user_css_urls;
 pub use link_rewrite::LinkRewriteTransform;
 pub use listing_generate::ListingGenerateTransform;
 pub use listing_render::ListingRenderTransform;
diff --git a/crates/quarto-core/tests/integration/format_css.rs b/crates/quarto-core/tests/integration/format_css.rs
new file mode 100644
index 000000000..6394eac76
--- /dev/null
+++ b/crates/quarto-core/tests/integration/format_css.rs
@@ -0,0 +1,427 @@
+/*
+ * tests/integration/format_css.rs
+ * Copyright (c) 2026 Posit, PBC
+ *
+ * Integration tests for user-declared stylesheets
+ * (`format.html.css` / document `css:`) in project renders:
+ * copy into the output tree, per-page href rebasing, the
+ * `_extensions/` relocation, and the Q-5-29 missing-file
+ * diagnostic. bd-format-css-not-copied-crn3bjdz.
+ */
+
+//! End-to-end tests for user-declared CSS in project renders.
+//!
+//! Each test writes a small fixture to a temp dir, drives it through
+//! `ProjectPipeline` (the same path `q2 render <project>` uses), then
+//! inspects rendered HTML and the on-disk output tree.
+//!
+//! What we pin (plan:
+//! `claude-notes/plans/2026-08-14-format-css-not-copied.md`):
+//!
+//! - project-root css is mirrored into the output tree
+//!   (`_site/styles.css`), Q1-parity;
+//! - `<link>` hrefs are depth-correct per page (`styles.css` at the
+//!   root, `../../styles.css` two levels down);
+//! - css living under `_extensions/` is relocated to
+//!   `<lib_dir>/quarto-contrib/quarto-project/…` so the `_extensions/`
+//!   tree itself never ships;
+//! - document-front-matter `css:` resolves against the document's own
+//!   directory;
+//! - a missing declared file emits Q-5-29 and the render completes
+//!   with the verbatim link still present (favicon-parity posture);
+//! - external URLs pass through untouched;
+//! - the default project type (which also serves books) gets the same
+//!   copy + rebase treatment — the fix must not be website-only;
+//! - revealjs decks link user css (previously dropped entirely).
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use tempfile::TempDir;
+
+use quarto_core::format::Format;
+use quarto_core::project::ProjectContext;
+use quarto_core::project::orchestrator::{ProjectPipeline, ProjectRenderSummary, project_type_for};
+use quarto_core::render_to_file::{RenderToFileOptions, render_to_file};
+use quarto_system_runtime::{NativeRuntime, SystemRuntime};
+
+fn canonical(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|_| path.to_path_buf())
+}
+
+fn write(path: &Path, contents: &str) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).unwrap();
+    }
+    std::fs::write(path, contents).unwrap();
+}
+
+fn runtime_arc() -> Arc<dyn SystemRuntime> {
+    Arc::new(NativeRuntime::new())
+}
+
+fn read(path: &Path) -> String {
+    std::fs::read_to_string(path).unwrap_or_else(|e| panic!("read {}: {}", path.display(), e))
+}
+
+/// Drive a fixture through `ProjectPipeline`. Same harness as
+/// `website_post_render.rs`: returns the project dir (kept alive past
+/// return) and the full render summary.
+fn render_project(fixture: impl FnOnce(&Path)) -> (PathBuf, ProjectRenderSummary) {
+    let temp = TempDir::new().unwrap();
+    let project_dir = canonical(temp.path());
+    fixture(&project_dir);
+
+    let runtime = runtime_arc();
+    let mut project = ProjectContext::discover(&project_dir, runtime.as_ref()).unwrap();
+
+    let options = RenderToFileOptions::default();
+    let project_type = project_type_for(&project);
+    let mut pipeline = ProjectPipeline::new(
+        &mut project,
+        project_type,
+        Format::html(),
+        "html",
+        &options,
+        runtime.clone(),
+    );
+    let summary = pollster::block_on(pipeline.run()).expect("pipeline");
+    assert!(
+        summary.pass1_failures.is_empty() && summary.pass2_failures.is_empty(),
+        "unexpected failures: pass1={:?} pass2={:?}",
+        summary.pass1_failures,
+        summary.pass2_failures
+    );
+
+    std::mem::forget(temp);
+    (project_dir, summary)
+}
+
+/// The stylesheet `<link>` lines of an HTML document, in order.
+fn stylesheet_links(html: &str) -> Vec<&str> {
+    html.lines()
+        .filter(|l| l.contains(r#"rel="stylesheet""#))
+        .map(str::trim)
+        .collect()
+}
+
+/// Assert `html` links `href` as a stylesheet.
+fn assert_links_css(html: &str, href: &str, context: &str) {
+    let expected = format!(r#"<link rel="stylesheet" href="{href}">"#);
+    assert!(
+        html.contains(&expected),
+        "{context}: expected {expected}; stylesheet links were: {:#?}",
+        stylesheet_links(html)
+    );
+}
+
+const PROJECT_CSS: &str = "body { --test-project-css: 1; }\n";
+const EXTENSION_CSS: &str = "body { --test-extension-css: 1; }\n";
+
+/// Standard two-page website fixture declaring `styles.css` at the
+/// project root. `deep/deeper/page.qmd` sits two levels down so the
+/// rebased href is unambiguous.
+fn website_with_root_css(project_dir: &Path) {
+    write(
+        &project_dir.join("_quarto.yml"),
+        "project:\n  type: website\n  output-dir: _site\n\
+         format:\n  html:\n    css:\n      - styles.css\n",
+    );
+    write(&project_dir.join("styles.css"), PROJECT_CSS);
+    write(
+        &project_dir.join("index.qmd"),
+        "---\ntitle: Home\n---\n\nH.\n",
+    );
+    write(
+        &project_dir.join("deep/deeper/page.qmd"),
+        "---\ntitle: Deep\n---\n\nD.\n",
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Copy: project-root css is mirrored into the output tree
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn website_format_css_copied_to_output_dir() {
+    let (project_dir, _summary) = render_project(website_with_root_css);
+    let copied = project_dir.join("_site/styles.css");
+    assert!(copied.exists(), "styles.css was not copied to _site/");
+    assert_eq!(
+        read(&copied),
+        PROJECT_CSS,
+        "copied stylesheet content must match the source"
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Rebase: hrefs are depth-correct per page
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn website_format_css_href_rebased_per_page() {
+    let (project_dir, _summary) = render_project(website_with_root_css);
+
+    let index_html = read(&project_dir.join("_site/index.html"));
+    let deep_html = read(&project_dir.join("_site/deep/deeper/page.html"));
+    assert_links_css(&index_html, "styles.css", "root page");
+    assert_links_css(&deep_html, "../../styles.css", "page two levels down");
+    assert!(
+        !deep_html.contains(r#"href="styles.css""#),
+        "deep page must not keep the verbatim project-relative href; links: {:#?}",
+        stylesheet_links(&deep_html)
+    );
+}
+
+/// User css must come after the theme stylesheet so user rules win the
+/// cascade (Q1 ordering).
+#[test]
+fn website_format_css_linked_after_theme() {
+    let (project_dir, _summary) = render_project(website_with_root_css);
+    let index_html = read(&project_dir.join("_site/index.html"));
+    let links = stylesheet_links(&index_html);
+    let theme_pos = links
+        .iter()
+        .position(|l| l.contains("quarto-theme"))
+        .unwrap_or_else(|| panic!("no theme link found: {links:#?}"));
+    let user_pos = links
+        .iter()
+        .position(|l| l.contains("styles.css"))
+        .unwrap_or_else(|| panic!("no user css link found: {links:#?}"));
+    assert!(
+        user_pos > theme_pos,
+        "user css must be linked after the theme stylesheet; links: {links:#?}"
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Relocation: css under _extensions/ ships via quarto-contrib
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn website_extension_css_relocated_to_quarto_contrib() {
+    let (project_dir, _summary) = render_project(|project_dir| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            "project:\n  type: website\n  output-dir: _site\n\
+             format:\n  html:\n    css:\n      - _extensions/acme/widget/widget.css\n",
+        );
+        write(
+            &project_dir.join("_extensions/acme/widget/widget.css"),
+            EXTENSION_CSS,
+        );
+        write(
+            &project_dir.join("index.qmd"),
+            "---\ntitle: Home\n---\n\nH.\n",
+        );
+        write(
+            &project_dir.join("deep/deeper/page.qmd"),
+            "---\ntitle: Deep\n---\n\nD.\n",
+        );
+    });
+
+    let relocated =
+        project_dir.join("_site/site_libs/quarto-contrib/quarto-project/acme/widget/widget.css");
+    assert!(
+        relocated.exists(),
+        "extension css was not relocated into site_libs/quarto-contrib/quarto-project/"
+    );
+    assert_eq!(read(&relocated), EXTENSION_CSS);
+    assert!(
+        !project_dir.join("_site/_extensions").exists(),
+        "the _extensions/ tree must never ship in the output"
+    );
+
+    let index_html = read(&project_dir.join("_site/index.html"));
+    let deep_html = read(&project_dir.join("_site/deep/deeper/page.html"));
+    assert_links_css(
+        &index_html,
+        "site_libs/quarto-contrib/quarto-project/acme/widget/widget.css",
+        "root page",
+    );
+    assert_links_css(
+        &deep_html,
+        "../../site_libs/quarto-contrib/quarto-project/acme/widget/widget.css",
+        "page two levels down",
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Document front matter: css resolves against the document's dir
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn document_front_matter_css_resolves_against_document_dir() {
+    let (project_dir, _summary) = render_project(|project_dir| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            "project:\n  type: website\n  output-dir: _site\n",
+        );
+        write(
+            &project_dir.join("index.qmd"),
+            "---\ntitle: Home\n---\n\nH.\n",
+        );
+        write(
+            &project_dir.join("deep/deeper/page.qmd"),
+            "---\ntitle: Deep\ncss: local.css\n---\n\nD.\n",
+        );
+        write(&project_dir.join("deep/deeper/local.css"), PROJECT_CSS);
+    });
+
+    assert!(
+        project_dir.join("_site/deep/deeper/local.css").exists(),
+        "document-relative css was not copied to _site/deep/deeper/"
+    );
+    let deep_html = read(&project_dir.join("_site/deep/deeper/page.html"));
+    assert_links_css(&deep_html, "local.css", "declaring page");
+    // The stylesheet belongs to that one document only.
+    let index_html = read(&project_dir.join("_site/index.html"));
+    assert!(
+        !index_html.contains("local.css"),
+        "front-matter css must not leak onto other pages"
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Missing file: Q-5-29, link still emitted, render completes
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn missing_format_css_emits_q_5_29_and_continues() {
+    let (project_dir, summary) = render_project(|project_dir| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            "project:\n  type: website\n  output-dir: _site\n\
+             format:\n  html:\n    css:\n      - nope.css\n",
+        );
+        write(
+            &project_dir.join("index.qmd"),
+            "---\ntitle: Home\n---\n\nH.\n",
+        );
+    });
+
+    // Favicon-parity posture: emit the (visibly broken) link rather
+    // than silently dropping the declaration.
+    let index_html = read(&project_dir.join("_site/index.html"));
+    assert_links_css(&index_html, "nope.css", "page with missing css");
+    assert!(
+        !project_dir.join("_site/nope.css").exists(),
+        "missing css must not be conjured into the output"
+    );
+
+    let diags: Vec<(Option<String>, String)> = summary
+        .project_diagnostics
+        .iter()
+        .map(|d| (d.code.clone(), d.title.clone()))
+        .collect();
+    assert!(
+        diags
+            .iter()
+            .any(|(code, title)| code.as_deref() == Some("Q-5-29") && title.contains("nope.css")),
+        "expected Q-5-29 naming 'nope.css'; got: {diags:?}"
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// External URLs: verbatim on every page, no copy, no diagnostic
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn external_url_css_passes_through_verbatim() {
+    let url = "https://example.com/x.css";
+    let (project_dir, summary) = render_project(|project_dir| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            &format!(
+                "project:\n  type: website\n  output-dir: _site\n\
+                 format:\n  html:\n    css:\n      - \"{url}\"\n"
+            ),
+        );
+        write(
+            &project_dir.join("index.qmd"),
+            "---\ntitle: Home\n---\n\nH.\n",
+        );
+        write(
+            &project_dir.join("deep/deeper/page.qmd"),
+            "---\ntitle: Deep\n---\n\nD.\n",
+        );
+    });
+
+    let index_html = read(&project_dir.join("_site/index.html"));
+    let deep_html = read(&project_dir.join("_site/deep/deeper/page.html"));
+    assert_links_css(&index_html, url, "root page");
+    assert_links_css(
+        &deep_html,
+        url,
+        "deep page (must not be made page-relative)",
+    );
+    assert!(
+        summary.project_diagnostics.is_empty(),
+        "an external css URL is valid config; got: {:?}",
+        summary
+            .project_diagnostics
+            .iter()
+            .map(|d| d.title.clone())
+            .collect::<Vec<_>>()
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Default project type (books' dispatch): same copy + rebase
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn default_project_format_css_copied_and_rebased() {
+    let (project_dir, _summary) = render_project(|project_dir| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            "project:\n  type: default\n  output-dir: _out\n\
+             format:\n  html:\n    css:\n      - styles.css\n",
+        );
+        write(&project_dir.join("styles.css"), PROJECT_CSS);
+        write(
+            &project_dir.join("index.qmd"),
+            "---\ntitle: Home\n---\n\nH.\n",
+        );
+        write(
+            &project_dir.join("docs/api.qmd"),
+            "---\ntitle: API\n---\n\nA.\n",
+        );
+    });
+
+    let copied = project_dir.join("_out/styles.css");
+    assert!(
+        copied.exists(),
+        "default project must copy declared css too (books ride this path)"
+    );
+    assert_eq!(read(&copied), PROJECT_CSS);
+
+    let index_html = read(&project_dir.join("_out/index.html"));
+    let api_html = read(&project_dir.join("_out/docs/api.html"));
+    assert_links_css(&index_html, "styles.css", "root page (default project)");
+    assert_links_css(&api_html, "../styles.css", "nested page (default project)");
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Revealjs: user css is linked (previously dropped entirely)
+// ═══════════════════════════════════════════════════════════════════
+
+#[test]
+fn revealjs_links_user_css() {
+    let temp = TempDir::new().unwrap();
+    let qmd_path = temp.path().join("talk.qmd");
+    write(
+        &qmd_path,
+        "---\ntitle: Talk\nformat: revealjs\ncss: custom.css\n---\n\n## One\n\nSlide.\n",
+    );
+    write(&temp.path().join("custom.css"), PROJECT_CSS);
+
+    let options = RenderToFileOptions {
+        quiet: true,
+        ..Default::default()
+    };
+    let result = render_to_file(&qmd_path, "revealjs", &options, runtime_arc())
+        .expect("revealjs render failed");
+    let html = read(&result.output_path);
+    assert_links_css(&html, "custom.css", "revealjs deck");
+}
diff --git a/crates/quarto-core/tests/integration/main.rs b/crates/quarto-core/tests/integration/main.rs
index 8a443f5d5..80ff7ad60 100644
--- a/crates/quarto-core/tests/integration/main.rs
+++ b/crates/quarto-core/tests/integration/main.rs
@@ -24,6 +24,7 @@ pub mod engine_output_parity;
 pub mod engine_visibility;
 pub mod extension_metadata;
 pub mod fail_fast;
+pub mod format_css;
 pub mod get_config_merge;
 pub mod idempotence;
 pub mod include_code_fence;
diff --git a/crates/quarto-error-catalog/error_catalog.json b/crates/quarto-error-catalog/error_catalog.json
index d0da0c736..f35292d38 100644
--- a/crates/quarto-error-catalog/error_catalog.json
+++ b/crates/quarto-error-catalog/error_catalog.json
@@ -1441,6 +1441,13 @@
     "docs_url": "https://quarto.org/docs/errors/project/Q-5-28",
     "since_version": "99.9.9"
   },
+  "Q-5-29": {
+    "subsystem": "project",
+    "title": "Declared Stylesheet Not Found",
+    "message_template": "A `css:` entry names a stylesheet that does not exist, so it was not copied into the output. Every page linking it will request a file that is not there. The path is resolved relative to the file that declares it. The render continues; the (broken) link is still emitted.",
+    "docs_url": "https://quarto.org/docs/errors/project/Q-5-29",
+    "since_version": "99.9.9"
+  },
   "Q-13-8": {
     "subsystem": "navigation",
     "title": "Unsupported toc-location value",
diff --git a/crates/quarto/tests/smoke-all/extensions/format-with-theme/test.qmd b/crates/quarto/tests/smoke-all/extensions/format-with-theme/test.qmd
index ac21c8197..b4badb17f 100644
--- a/crates/quarto/tests/smoke-all/extensions/format-with-theme/test.qmd
+++ b/crates/quarto/tests/smoke-all/extensions/format-with-theme/test.qmd
@@ -8,7 +8,8 @@ _quarto:
       ensureCssRegexMatches:
         - ["fmt-theme-marker", "#0a1b2c"]
       ensureFileRegexMatches:
-        - ["_extensions/fancyfmt/fmt-style\\.css"]
+        - ["quarto-contrib/quarto-project/fancyfmt/fmt-style\\.css"]
+        - ["_extensions/fancyfmt"]
 ---
 
 ## Format With Theme
@@ -17,6 +18,9 @@ A format extension bundling a theme SCSS (`fmt-theme.scss`) and a CSS
 file (`fmt-style.css`) next to its `_extension.yml`. The compiled CSS
 must contain the bundled theme's rule (rebased ext-dir → doc-dir,
 bd-of20unsb), and the rendered HTML must link the bundled CSS at its
-rebased path.
+**relocated** path — `_extensions/` files ship via
+`quarto-contrib/quarto-project/` and never at their source path
+(bd-format-css-not-copied-crn3bjdz), so the link keeps working when
+output is written to a separate `output-dir`.
 
 A [span]{.fmt-theme-marker} using the theme rule.
diff --git a/docs/errors/project/Q-5-29.qmd b/docs/errors/project/Q-5-29.qmd
new file mode 100644
index 000000000..f5c1e1549
--- /dev/null
+++ b/docs/errors/project/Q-5-29.qmd
@@ -0,0 +1,63 @@
+---
+title: "Declared Stylesheet Not Found"
+description: "A `css:` entry names a stylesheet that does not exist, so it was not copied into the output."
+code: Q-5-29
+subsystem: project
+status: complete
+since: "99.9.9"
+categories:
+  - project
+---
+
+# `Q-5-29` — Declared Stylesheet Not Found
+
+> A `css:` entry names a stylesheet that does not exist, so it was
+> not copied into the output. Every page linking it will request a
+> file that is not there. The render continues; the (broken) link is
+> still emitted.
+
+## What this means
+
+A document or project can attach extra stylesheets to its HTML
+output with the `css` option:
+
+```yaml
+# _quarto.yml
+format:
+  html:
+    css:
+      - styles.css
+```
+
+Quarto resolves each entry **relative to the file that declares
+it**: entries in `_quarto.yml` resolve against the project root,
+entries in a directory's `_metadata.yml` against that directory, and
+entries in a document's front matter against the document's own
+directory. A leading `/` anchors the path at the project root from
+any of those places.
+
+When the resolved file exists, Quarto copies it into the output
+tree and emits a depth-correct `<link>` on every page. This warning
+fires when the file does **not** exist: nothing is copied, and the
+`<link>` is emitted with the path exactly as you wrote it — visibly
+broken in the browser's network tab rather than silently absent.
+
+## Common causes
+
+- **A typo in the path**, or a file that was moved or renamed
+  without updating the `css` entry.
+- **A path written relative to the wrong anchor** — for example, a
+  document in `posts/2026/` declaring `css: styles.css` for a file
+  that actually lives at the project root. From front matter that
+  entry names `posts/2026/styles.css`; write `/styles.css` (or
+  `../../styles.css`) instead.
+- **A stylesheet that is generated later** by a tool that has not
+  run yet.
+
+## How to fix it
+
+Check the path in the `css` entry against the anchor of the file
+that declares it, or add the missing stylesheet. If the stylesheet
+belongs to the project as a whole, declaring it once in
+`_quarto.yml` (project-root-relative) is usually clearer than
+repeating it per document.

From 86a6f79da8f10f4847e4c642e92b9a47475c284e Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Fri, 14 Aug 2026 17:09:33 -0500
Subject: [PATCH 5/6] Gate Q-5-29 emission to native renders
 (bd-format-css-not-copied-crn3bjdz)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The WASM preview/hub leg runs the same orchestrator and metadata
merge, but its runtime probes the VFS — which is not authoritative
for non-qmd project files. A stylesheet that exists on disk but is
not synced produced a false 'Q-5-29 css refers to missing file'
warning in the preview overlay (observed in a real browser session
against q2 preview). Emit the missing-css diagnostics only in native
renders, where the output tree is real.

Verified in the browser after rebuilding the WASM -> SPA -> q2
chain: the preview renders the fixture with no warning overlay.
Preview still does not APPLY user css (VFS-mode transform no-op,
per the settled design) — filed as bd-b3oq2fsy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 claude-notes/plans/2026-08-14-format-css-not-copied.md | 6 +++---
 crates/quarto-core/src/project/orchestrator.rs         | 7 ++++++-
 crates/quarto-core/src/stage/stages/metadata_merge.rs  | 8 ++++++++
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/claude-notes/plans/2026-08-14-format-css-not-copied.md b/claude-notes/plans/2026-08-14-format-css-not-copied.md
index 17f4119eb..56fc0f7b7 100644
--- a/claude-notes/plans/2026-08-14-format-css-not-copied.md
+++ b/claude-notes/plans/2026-08-14-format-css-not-copied.md
@@ -367,9 +367,9 @@ Implementation runs on branch `braid/bd-format-css-not-copied-crn3bjdz`
 ### Phase 4 — end-to-end verification + follow-ups
 
 - [x] `cargo run --bin q2 -- render` on the investigation fixture; inspect output (record snippet in plan)
-- [ ] Re-check the Connect docs repro
-- [ ] Verify `q2 preview` behavior; file preview follow-up strand if broken
-- [ ] Full `cargo xtask verify` green
+- [x] Re-check the Connect docs repro (2026-08-14, branch binary: both css files copied, deep hrefs `../../styles.css` + relocated quarto-contrib path — matches Q1 table)
+- [x] Verify `q2 preview` behavior; filed follow-up **bd-b3oq2fsy** (user css not applied in VFS mode; also fixed a false Q-5-29 in the preview overlay by cfg-gating emission to native)
+- [x] Full `cargo xtask verify` green (14 legs, 2026-08-14; workspace re-run after the wasm cfg fix: 12182 native + 131 wasm)
 - [ ] User-facing docs if applicable
 
 ## Proposed phases (draft)
diff --git a/crates/quarto-core/src/project/orchestrator.rs b/crates/quarto-core/src/project/orchestrator.rs
index 033e1891a..666a5085a 100644
--- a/crates/quarto-core/src/project/orchestrator.rs
+++ b/crates/quarto-core/src/project/orchestrator.rs
@@ -965,7 +965,12 @@ impl<'a, R: Pass2Renderer> ProjectPipeline<'a, R> {
         // Project-config `css:` entries naming missing files warn once
         // per render here — not once per page in the merge, which is
         // where document-layer `css:` mistakes are diagnosed instead
-        // (bd-format-css-not-copied-crn3bjdz).
+        // (bd-format-css-not-copied-crn3bjdz). Native only: in the WASM
+        // preview/hub the runtime probes the VFS, which is not
+        // authoritative for non-qmd project files (a stylesheet that
+        // exists on disk may simply not be synced), so the same check
+        // there produced false Q-5-29 warnings in the preview overlay.
+        #[cfg(not(target_arch = "wasm32"))]
         initial_diagnostics.extend(crate::project::format_css::missing_project_css_diagnostics(
             self.project,
             self.format.identifier.as_str(),
diff --git a/crates/quarto-core/src/stage/stages/metadata_merge.rs b/crates/quarto-core/src/stage/stages/metadata_merge.rs
index cba9b4369..9ff00c693 100644
--- a/crates/quarto-core/src/stage/stages/metadata_merge.rs
+++ b/crates/quarto-core/src/stage/stages/metadata_merge.rs
@@ -384,7 +384,15 @@ impl PipelineStage for MetadataMergeStage {
             &document_dir,
             ctx.runtime.as_ref(),
         ));
+        // Native only: the WASM VFS is not authoritative for non-qmd
+        // project files (an on-disk stylesheet may simply not be
+        // synced), so surfacing these there yields false warnings.
+        // See the matching gate on `missing_project_css_diagnostics`
+        // in the orchestrator.
+        #[cfg(not(target_arch = "wasm32"))]
         ctx.add_diagnostics(css_diagnostics);
+        #[cfg(target_arch = "wasm32")]
+        drop(css_diagnostics);
 
         // Layer 5: Runtime metadata (flattened for base format)
         let runtime_layer = runtime_meta_json

From 420e61f7f95fe43bc08b9adc50c59e3f6e7a932c Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Fri, 14 Aug 2026 17:10:08 -0500
Subject: [PATCH 6/6] Plan wrap-up: all phases complete
 (bd-format-css-not-copied-crn3bjdz)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-14-format-css-not-copied.md        | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/claude-notes/plans/2026-08-14-format-css-not-copied.md b/claude-notes/plans/2026-08-14-format-css-not-copied.md
index 56fc0f7b7..5859dbd09 100644
--- a/claude-notes/plans/2026-08-14-format-css-not-copied.md
+++ b/claude-notes/plans/2026-08-14-format-css-not-copied.md
@@ -3,10 +3,12 @@
 **Date:** 2026-08-14
 **Braid:** bd-format-css-not-copied-crn3bjdz (bug, p1, label `websites`)
 **Checkout:** main checkout, branch `main` @ `10d86829` (investigation only — no worktree/branch created)
-**Status:** Implementation in progress on branch
-`braid/bd-format-css-not-copied-crn3bjdz` (Phases 0–3 complete, full
-workspace suite green 12182/12182; Phase 4 verification underway — see
-"Phase 4 evidence").
+**Status:** Implementation complete on branch
+`braid/bd-format-css-not-copied-crn3bjdz` (commits `37758160` +
+`86a6f79d` on top of the investigation commits). All phases done; full
+`cargo xtask verify` green; preview verified in a real browser (false
+Q-5-29 fixed, css-application gap filed as bd-b3oq2fsy). Awaiting
+push/PR approval.
 
 ## Phase 4 evidence (end-to-end, real binary)
 
@@ -370,7 +372,7 @@ Implementation runs on branch `braid/bd-format-css-not-copied-crn3bjdz`
 - [x] Re-check the Connect docs repro (2026-08-14, branch binary: both css files copied, deep hrefs `../../styles.css` + relocated quarto-contrib path — matches Q1 table)
 - [x] Verify `q2 preview` behavior; filed follow-up **bd-b3oq2fsy** (user css not applied in VFS mode; also fixed a false Q-5-29 in the preview overlay by cfg-gating emission to native)
 - [x] Full `cargo xtask verify` green (14 legs, 2026-08-14; workspace re-run after the wasm cfg fix: 12182 native + 131 wasm)
-- [ ] User-facing docs if applicable
+- [x] User-facing docs: the Q-5-29 page documents the resolution rules (per-layer anchors, leading `/`); rendered through q2 and inspected. The docs' own `css: styles.css` example (guides/projects/create.qmd) now actually works. No further docs page needed.
 
 ## Proposed phases (draft)