diff --git a/claude-notes/plans/2026-08-14-toc-location.md b/claude-notes/plans/2026-08-14-toc-location.md
new file mode 100644
index 000000000..22777a31c
--- /dev/null
+++ b/claude-notes/plans/2026-08-14-toc-location.md
@@ -0,0 +1,304 @@
+# toc-location option (left/right/body); unlocks banner toc-left class (bd-e2kpwy7n)
+
+**Date:** 2026-08-14
+**Braid:** bd-e2kpwy7n
+**Branch:** investigated on `main` (worktree `.worktrees/bd-nn2fou8h-execute-visibility`, reused after its strand merged)
+**Status:** Implemented 2026-08-14 on branch `braid/bd-e2kpwy7n-toc-location` (phases 0-4 complete; full `cargo xtask verify` passed 2026-08-14, all 14 steps including hub/WASM legs). Awaiting push approval.
+
+User-stated scope note: `external-sources/quarto-cli` is context, not a
+contract — what matters is a mechanism that renders TOCs in alternative
+locations (`left` first among them), not byte-for-byte Q1 parity.
+
+## Design decisions (user-aligned, 2026-08-14)
+
+1. **Value scope:** implement `left`, `right`, `body` now. `left-body` /
+   `right-body` warn-and-fall-back (`left-body` → `left`, `right-body` →
+   `right`) with a diagnostic; the clone behavior is a follow-up strand.
+2. **Two mechanisms, Q1 parity:** port both `left` layouts — standalone
+   (`#quarto-sidebar-toc-left` + `.page-columns.toc-left` grid) and website
+   (TOC merged into `nav#quarto-sidebar`, `body.floating` grid). Possible
+   unification is a future cleanup, not this strand.
+3. **Website merge lives in `SidebarRenderTransform`** (option (a)): the
+   rendered sidebar fragment contains the TOC, so custom templates that
+   emit `$rendered.navigation.sidebar$` keep working with no new
+   variables. Cost: `TocRenderTransform` must run before
+   `SidebarRenderTransform` (both Navigation-phase — reorder is legal),
+   and SidebarRender grows a synthesize-floating-sidebar branch for
+   website + left + no configured sidebar.
+4. **`body` ships the decorated markup** (`nav-link`,
+   `data-scroll-target`, `.toc-active`) — deviation from Q1's plain list,
+   deliberate: scroll-spying is likely coming and the classes are inert
+   without the sidebar JS.
+5. **No empty right-margin shell:** when the TOC moves left, q2 keeps
+   omitting `#quarto-margin-sidebar` entirely (deviation from Q1's empty
+   `zindex-bottom` shell — Q1's text-centric infra makes elision hard; we
+   can do better).
+6. **Banner gate:** `banner-header-class: toc-left` when the (normalized)
+   location is exactly `left`. The `left-body` question is recorded on the
+   `*-body` follow-up strand (when it lands, the gate should cover
+   `left-body` too, fixing Q1's latent inconsistency).
+7. **Preview parity is a follow-up strand** — `q2 preview`'s `TocSlot`
+   keeps showing the TOC on the right until that strand lands; flagged
+   there explicitly.
+
+Follow-up strands filed from this design: see "Follow-up strands" below.
+
+## Triage verdict
+
+**Ready to design.** (Superseded: design questions answered above; now
+ready to implement.) The gap is confirmed at HEAD, the Q1 mechanism is
+fully mapped, the q2 insertion points are identified, and the SCSS +
+template hooks are already ported and inert.
+
+## Issue context
+
+Q2 has no `toc-location` option — the TOC always renders in the right margin
+sidebar (`#quarto-margin-sidebar`). Filed 2026-07-17 as a P2 feature,
+follow-up from the title-block parity epic (the banner `toc-left`
+header-class hook was ported inert). On 2026-08-14 it gained real-world
+impact data from the Posit Connect docs port: `api/index.html` is a 1.8 MB
+OpenAPI reference whose only navigation is a 201-entry TOC with
+`toc-location: left` — the port's worst page in chrome comparisons, and the
+only page site-wide where Q1 emits `#quarto-sidebar` and q2 emits none.
+
+Committed minimal repro (external):
+`/Users/cscheid/repos/github/cscheid/q2-connect-docs/llms-info/repros/toc-location-left/`
+(re-verified unimplemented at 0.19.0/0.20.0/0.21.0 and HEAD `3ac596e0`).
+Local copy of the same fixture:
+`claude-notes/plans/toc-location-investigation/repro/`.
+
+## Dependency graph
+
+- **discovered-from**: bd-y71ga2l8 (closed) — title-block parity Phase 7
+  (docs + follow-up strands). The title-block work ported the banner
+  `banner-header-class` template hook verbatim but left it inert because
+  its only Q1 producer derives `toc-left` from `toc-location`, which q2
+  lacked. This strand is the missing producer.
+- No incoming `blocks` edges; no children. Priority pressure comes from the
+  Connect-docs port (origin strand br-toc-location-left-q7hl5jgj in that
+  repo's skein), not from the q2 graph.
+
+## What the code looks like today
+
+The file references in the strand are current at HEAD:
+
+- `crates/quarto-core/src/template.rs:213-235` — `FULL_HTML_TEMPLATE`
+  hardcodes the TOC into `<div id="quarto-margin-sidebar">` on the right;
+  `#quarto-content` classes are baked in (no `toc-left` variable).
+- `crates/quarto-core/src/template.rs:337` — the inert banner hook:
+  `$if(quarto-template-params.banner-header-class)$` on
+  `#title-block-header`.
+- `crates/quarto-core/src/transforms/title_banner.rs:41` — documents the
+  deliberately-unported `toc-left` producer.
+- `crates/quarto-core/src/transforms/toc_render.rs` — renders
+  `navigation.toc` → `rendered.navigation.toc` (inner `<ul>` only; entries
+  carry `nav-link` + `data-scroll-target` unconditionally).
+- `crates/quarto-core/src/transforms/sidebar_render.rs` — renders the
+  website sidebar → `rendered.navigation.sidebar` (a complete
+  `nav#quarto-sidebar` fragment via `quarto_navigation::sidebar_to_html`)
+  and writes `rendered.navigation.body-classes` = `"nav-sidebar
+  floating|docked"`; skips entirely when `navigation.sidebar` is absent.
+- `render_with_compiled_template` (`template.rs:697-733`) — body-class
+  precedence: user override → sidebar body-classes → empty-when-TOC →
+  `fullcontent`.
+- SCSS is **already ported** in `resources/scss/bootstrap/_bootstrap-rules.scss`:
+  `.page-columns.toc-left` grids (wide/mid/narrow), `.sidebar.toc-left`
+  placement, `#quarto-sidebar-toc-left` responsive hiding, sticky rules.
+- Preview: `ts-packages/preview-renderer/src/q2-preview/chromeSlots.tsx`
+  `TocSlot` hardcodes `#quarto-margin-sidebar` too (shape contract with the
+  template).
+- No `toc-location` schema entry anywhere in q2.
+
+Symptom re-confirmed at HEAD (2026-08-14, `main` after PR #530):
+`cargo run --bin q2 -- render .` on the local repro puts `nav#TOC` inside
+`#quarto-margin-sidebar` and emits zero `#quarto-sidebar` (or
+`#quarto-sidebar-toc-left`) elements — output inspected, see
+`toc-location-investigation/repro/README.md`.
+
+Pre-flight note: `cargo xtask verify --skip-hub-build` at HEAD had exactly
+one failure, `quarto-preview::integration
+config_endpoint::config_reports_embedded_asset_manifest_hashes` — a stale
+local `q2-preview-spa/dist/` (built before `f366cb5d` introduced
+`spa-manifest.json`). `cargo xtask build-q2-preview-spa` regenerated the
+manifest and the test passes; unrelated to this strand.
+
+## How Q1 does it (mechanism summary, from external-sources/quarto-cli 1.10.15)
+
+See `claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md`
+for the full file:line map.
+
+- **Option**: `toc-location` enum `["body", "left", "right", "left-body",
+  "right-body"]`, default `right`, HTML-doc formats only
+  (`src/resources/schema/document-toc.yml:36-52`).
+- **Mechanism**: templates emit a `div#quarto-toc-target` placeholder; a DOM
+  postprocessor (`format-html-bootstrap.ts:342-412`) moves `nav[role=doc-toc]`
+  into it (adding `.toc-active`, `nav-link`, `data-scroll-target`,
+  collapse classes). q2 re-expresses this as template/transform logic
+  (no-DOM-postprocessor rule).
+- **Two layout regimes for `left`:**
+  - *Standalone/article path* (`before-body-article.ejs`): `#quarto-content`
+    gets class `toc-left`; a `div#quarto-sidebar-toc-left.sidebar.toc-left`
+    holds the TOC; grid comes from `.page-columns.toc-left` mixins gated on
+    `body:not(.floating):not(.docked)`.
+  - *Website path* (`nav-before-body.ejs` + `sidebar.ejs`): the TOC target
+    goes **inside `nav#quarto-sidebar`** — merged after nav items when a
+    sidebar exists, or as the sole content of a synthesized
+    `nav#quarto-sidebar … floating` when no sidebar is configured. Body gets
+    `floating`/`docked`, and the `body.floating` grid (NOT `toc-left`)
+    provides the left column. This is the repro's shape.
+- **`body`**: no target emitted → the TOC stays where Pandoc put it in
+  `main` (Q1 leaves it undecorated; q2 will decorate per decision 4).
+- **`left-body` / `right-body`**: sidebar TOC plus a plain clone
+  (`id="TOC-body"`, `.toc-actions` stripped) left in the body. Deferred.
+- **Banner**: `format-html-title.ts:169-175` sets
+  `banner-header-class: toc-left` when `toc-location === "left"`.
+- **About pages** force `right`; **manuscripts** default to `left` (both
+  out of scope here; noted for the project-types work).
+
+## Phases
+
+### Phase 0 — Test plan (TDD: failing tests first)
+
+End-to-end style per repo policy (route through `render_document_to_file`
+/ project render, not `HtmlRenderConfig::default()` shortcuts):
+
+Written 2026-08-14 in
+`crates/quarto-core/tests/integration/toc_location.rs`; verified failing
+at the expected assertions (9 failed, 2 controls passed) before any
+implementation.
+
+- [x] **Website + `left`, no configured sidebar** (repro shape): output has
+      `nav#quarto-sidebar … floating` containing `nav#TOC`; body classes
+      include `floating`; NO `#quarto-margin-sidebar` (decision 5); no TOC
+      in the margin region.
+- [x] **Website + `left`, with configured sidebar**: single
+      `nav#quarto-sidebar`; nav items first, TOC appended after; no second
+      container; margin sidebar omitted.
+- [x] **Standalone doc + `left`**: `#quarto-content` class list gains
+      `toc-left`; `div#quarto-sidebar-toc-left.sidebar.toc-left` contains
+      `nav#TOC`; body classes do NOT include `floating`/`docked`; margin
+      sidebar omitted.
+- [x] **`body`**: `nav#TOC` renders inside `main#quarto-document-content`
+      (after the title block, before content), decorated markup; no margin
+      sidebar, no left containers.
+- [x] **`right` / unset**: current output byte-stable (snapshot-neutral —
+      guard the no-churn goal).
+- [x] **Banner + `left`**: `#title-block-header` class list contains
+      `toc-left` (template.rs:337 hook fires).
+- [x] **`left-body` / `right-body`**: warning diagnostic emitted; placement
+      falls back to `left` / `right` respectively.
+- [x] **Margin-categories interaction**: pinned at the template-unit
+      level (`full_template_relocated_toc_keeps_categories_only_margin`
+      in template.rs — a full listing fixture would have been heavier
+      than the contract it pins): a relocated TOC does not render in
+      the margin, categories keep their margin shell.
+
+### Phase 1 — Option plumbing
+
+- [x] Read `toc-location` from merged metadata with `as_plain_text` (the
+      `metadata-as-str` lint exists for exactly this key shape).
+- [x] Normalize: `left` | `right` | `body`; `*-body` → warn + fallback;
+      unknown value → diagnostic + default `right`.
+- [x] Publish `rendered.navigation.toc-location` (string) early in the
+      Navigation phase so TocRender, SidebarRender, TitleBanner, and the
+      template all read one source of truth. (Smallest home: a tiny
+      transform or a helper called from `toc_generate`/`toc_render` —
+      decide at implementation; must be readable before SidebarRender.)
+
+### Phase 2 — Placement
+
+- [x] Reorder pipeline: `TocRenderTransform` before
+      `SidebarRenderTransform` (both `TransformPhase::Navigation`; verify
+      no other ordering dependency between them — sidebar/breadcrumb
+      comment at pipeline.rs:1383 mentions ordering vs TocRender, re-check
+      why).
+- [x] `SidebarRenderTransform`: when location is `left` and a website
+      sidebar exists → append the rendered TOC (plus `h2#toc-title`) inside
+      the `nav#quarto-sidebar` fragment (seam in
+      `quarto_navigation::sidebar_to_html` or post-append in the
+      transform). When location is `left`, website project, no configured
+      sidebar → synthesize the Q1 wrapper
+      (`nav#quarto-sidebar.sidebar.collapse.collapse-horizontal.quarto-sidebar-collapse-item.sidebar-navigation.floating.overflow-auto`)
+      holding only the TOC, and write body-classes `floating` (decide
+      whether `nav-sidebar` belongs in that class list — it's q2's own
+      addition; check its SCSS consumers).
+- [x] `FULL_HTML_TEMPLATE`: gate the right-margin TOC region on location
+      `right`; add the standalone-left `#quarto-sidebar-toc-left` block +
+      `toc-left` class on `#quarto-content` (new template variable); add
+      the `body` emission point in `main`. Standalone-left must not claim
+      the website wrapper (no `floating`).
+- [x] Body-class precedence (`render_with_compiled_template`): confirm the
+      four existing cases still hold; standalone-left rides the existing
+      "TOC present → empty class" case (grid comes from `#quarto-content`'s
+      `toc-left`, not body).
+- [x] Update the stale comments: template.rs:296-298 ("which Q2 doesn't
+      support yet") and title_banner.rs:41-43.
+
+### Phase 3 — Banner producer
+
+- [x] `TitleBannerTransform` (or the title pipeline stage that owns
+      `quarto-template-params`) writes
+      `quarto-template-params.banner-header-class = "toc-left"` when banner
+      mode is active and normalized location is `left`.
+- [x] Module docs updated (title_banner.rs deviation note becomes a
+      pointer to this plan).
+
+### Phase 4 — Schema, docs, E2E
+
+- [x] Schema entry: **N/A** — q2 has no document-option schema
+      infrastructure to extend (quarto-yaml-validation is external and
+      unused here); value validation lives in `TocLocationTransform`
+      (Q-13-8). Revisit if/when a doc-options schema lands.
+- [x] Docs page in `docs/` (user-facing usage, not internals; rendered
+      with `cargo run --bin q2 -- render docs/`).
+- [x] End-to-end verification (output inspected in both cases):
+      - Website regime: `cargo run --bin q2 -- render .` in
+        `claude-notes/plans/toc-location-investigation/repro/` →
+        `<nav id="quarto-sidebar" class="sidebar sidebar-navigation
+        sidebar-floating" role="doc-toc">` containing `nav#TOC`, zero
+        `#quarto-margin-sidebar`, `<body class="nav-sidebar floating
+        quarto-light">`.
+      - Standalone regime: bare `doc.qmd` with `toc-location: left` →
+        `<div id="quarto-content" class="… page-layout-article
+        toc-left">`, `<div id="quarto-sidebar-toc-left" class="sidebar
+        toc-left">` containing `nav#TOC`, `<body class="quarto-light">`.
+      - The real Connect-docs `api/index.html` (1.8 MB, 201 entries) has
+        not been re-rendered here — the minimal repro mirrors its shape;
+        worth a spot-check from the q2-connect-docs project when
+        convenient.
+- [x] Snapshot review: zero `.snap` files changed — the `right`/default
+      path is byte-stable (all 12,111 workspace tests green with no
+      snapshot updates).
+
+## Follow-up strands
+
+- **`*-body` clone behavior** (`left-body`/`right-body`): body clone
+  `id="TOC-body"` with actions stripped, plus lifting the warn-fallback.
+  Must record the banner-gate constraint: when `left-body` lands, the
+  banner `toc-left` class should cover it too (fixing Q1's latent
+  `=== "left"` inconsistency). Filed as bd-jclcm0in.
+- **Preview parity**: teach `TocSlot`/`chromeSlots.tsx` +
+  `PreviewDocument.tsx` the published `rendered.navigation.toc-location`;
+  until then `q2 preview` shows the TOC on the right for left/body docs.
+  Filed as bd-tqijrhsu.
+
+## Risks / tradeoffs
+
+- `FULL_HTML_TEMPLATE`'s `#quarto-content` class list is baked in; the new
+  `toc-left` template variable touches the body-class precedence logic
+  (`template.rs:697-733`) — the subtle `fullcontent`-vs-empty fallback has
+  bitten before (bd-mgoh); Phase 0 pins all precedence cases.
+- The synthesized floating sidebar interacts with
+  `SidebarRenderTransform`'s skip conditions and the `nav-sidebar`
+  body-class consumers — audit before choosing the class list.
+- Snapshot churn: keep `right` byte-stable so the diff stays reviewable.
+- Preview/template shape drift until the preview follow-up lands — the
+  strand records this explicitly.
+
+## Investigation artifacts
+
+- `claude-notes/plans/toc-location-investigation/repro/` — minimal website
+  repro (mirrors the committed external repro).
+- `claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md` —
+  full Q1 exploration report (file:line references into
+  external-sources/quarto-cli).
diff --git a/claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md b/claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md
new file mode 100644
index 000000000..afd176cfd
--- /dev/null
+++ b/claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md
@@ -0,0 +1,185 @@
+# Q1 `toc-location` mechanism notes (bd-e2kpwy7n investigation)
+
+Exploration of `external-sources/quarto-cli` (1.10.15), 2026-08-14. All
+paths below are relative to `external-sources/quarto-cli/` unless noted.
+
+## 1. Declaration / read sites
+
+- Constant: `src/config/constants.ts:603` — `kTocLocation = "toc-location"`.
+- Schema: `src/resources/schema/document-toc.yml:36-52` —
+  `enum: ["body", "left", "right", "left-body", "right-body"]`, default
+  `right`, `formats: [$html-doc]`.
+- Readers (all six in the tree):
+  - `src/format/html/format-html-bootstrap.ts:127-129` — standalone/article path
+  - `src/format/html/format-html-bootstrap.ts:349` — double-TOC (`*-body`) detection
+  - `src/format/html/format-html-title.ts:171` — banner header class
+  - `src/project/types/website/website-navigation.ts:252-256, 302` — website path
+  - `src/project/types/manuscript/manuscript.ts:454-455` — manuscripts default to `left`
+  - `src/project/types/website/about/website-about.ts:106` — about pages force `right` (and `toc: false`)
+- No runtime normalization beyond the YAML enum; the raw string is passed to
+  EJS and compared with `===`.
+
+## 2. Placement mechanism
+
+Two template paths emit a `div#quarto-toc-target` placeholder; one shared
+DOM postprocessor moves `nav[role="doc-toc"]` into it.
+
+### 2a. Standalone / non-website article
+
+`src/format/html/format-html-bootstrap.ts:126-142` renders
+`src/resources/formats/html/templates/before-body-article.ejs`:
+
+```ejs
+<%
+const navbarTocLeft = tocLocation === "left" || tocLocation === "left-body";
+const navbarTocRight = tocLocation === "right" || tocLocation === "right-body";
+%>
+<div id="quarto-content" class="page-columns page-rows-contents page-layout-<%- pageLayout %><%- (navbarTocLeft) ? " toc-left" : ""%>">
+<% if (navbarTocLeft) { %>
+<div id="quarto-sidebar-toc-left" class="sidebar toc-left">
+  <div id="quarto-toc-target"></div>
+</div>
+<% } %>
+<div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
+  <% if (navbarTocRight) { %>
+  <div id="quarto-toc-target"></div>
+  <% } %>
+</div>
+<main class="content" id="quarto-document-content">
+```
+
+`body` produces **no** target at all. `#quarto-margin-sidebar` is always
+emitted (it may hold margin content even without a TOC).
+
+### 2b. Website projects
+
+`src/project/types/website/website-navigation.ts:252-256, 302, 379` →
+`src/resources/projects/website/templates/nav-before-body.ejs:3-4, 111-125`:
+
+```ejs
+const navbarTocLeft = nav['toc-location'] === "left" || nav['toc-location'] === "left-body";
+...
+<!-- sidebar -->
+<% if (nav.sidebar || navbarTocLeft) { %>
+  <% partial('sidebar.ejs', { sidebar: nav.sidebar, sidebarStyle: nav.sidebarStyle, navbar: !!nav.navbar, toc: navbarTocLeft, ... }) %>
+<% } %>
+<!-- margin-sidebar -->
+<% if (nav.layout === "article" || nav.layout === "full") { %>
+    <div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
+      <% if (nav.hasToc && navbarTocRight) { %>
+        <div id="quarto-toc-target"></div>
+      <% } %>
+    </div>
+<% } %>
+```
+
+`src/resources/projects/website/templates/sidebar.ejs:1, 95-97`:
+
+```ejs
+<nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation <%- sidebarStyle || (toc ? "floating" : "") %> overflow-auto">
+...
+  <% if (toc) { %>
+    <div id="quarto-toc-target"></div>
+  <% } %>
+</nav>
+<div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" ...></div>
+```
+
+Asymmetries vs. the standalone path: no `toc-left` class on
+`#quarto-content`; the left target lives inside `nav#quarto-sidebar`, not a
+separate `#quarto-sidebar-toc-left`.
+
+- **Nav sidebar + left TOC** → one `nav#quarto-sidebar`, nav items first,
+  TOC appended after — merged, no second container.
+- **No nav sidebar + left TOC (in a website)** → `sidebar.ejs` renders with
+  `sidebar === undefined`; the wrapper holds only the TOC target and gets
+  class `floating` (ternary fallback). `website-navigation.ts:538-543` then
+  latches `floating` onto `<body>`, so the `page-columns-float-*` grids
+  apply — **not** the `toc-left` grids, which are gated on
+  `body:not(.floating):not(.docked)`.
+
+### 2c. The mover (shared DOM postprocessor)
+
+`src/format/html/format-html-bootstrap.ts:342-412`
+(`bootstrapHtmlPostprocessor`):
+
+- `right`/`left` → `toc.remove(); tocTarget.replaceWith(toc)`; adds
+  `.toc-active`, `nav-link` classes, `data-scroll-target`, `.collapse` on
+  nested `ul`s, `data-toc-expanded`.
+- `body` → `tocTarget` is null → TOC left in `main`, **no** decorations
+  (plain static list; smoke test
+  `tests/docs/smoke-all/issues/3473-toc-side-body/body.qmd`).
+- `left-body`/`right-body` → clone with `id="TOC-body"` (`.toc-actions`
+  stripped) inserted before the original, original moved to the sidebar.
+
+## 3. Layout / CSS
+
+SCSS (already ported into q2's `resources/scss/bootstrap/`):
+
+| What | Q1 file:line |
+|---|---|
+| `.page-columns.toc-left` wide grid | `_bootstrap-rules.scss:62-70` |
+| `.page-columns.toc-left` mid grid | `_bootstrap-rules.scss:145-152` |
+| narrow collapse + `nav[role="doc-toc"] { display:none }` | `_bootstrap-rules.scss:219-232` |
+| `.sidebar.toc-left` grid placement (`page-start / body-start`) | `_bootstrap-rules.scss:303-306` |
+| toc-left margin-element reflow into body column | `_bootstrap-rules.scss:545-557` |
+| `#quarto-margin-sidebar` / `#quarto-sidebar-toc-left` hidden below md | `_bootstrap-rules.scss:574-581` |
+| sticky sidebar rules | `_bootstrap-rules.scss:1075-1087` |
+| sidebar-TOC typography/active/border | `_bootstrap-rules.scss:1201-1330` |
+| `page-columns-tocleft-wide/-mid` mixins | `_bootstrap-mixins.scss:1302-1334` |
+| grid track vars | `_bootstrap-mixins.scss:846-895` |
+
+`.sidebar.quarto-banner-title-block-sidebar` (`_bootstrap-rules.scss:1090-1094`)
+appears dead — nothing assigns the class.
+
+## 4. Banner interaction
+
+`src/format/html/format-html-title.ts:169-175`: when banner (or manuscript)
+and `toc-location === "left"` **exactly** (`left-body` misses it — latent Q1
+inconsistency), set `templateParams["banner-header-class"] = "toc-left"`.
+Consumed by `templates/banner/title-block.html:2` and
+`templates/manuscript/title-block.html:1` — same `$if$` hook q2 already
+carries at `crates/quarto-core/src/template.rs:337`. Why needed: Q1 moves
+the banner header out of `#quarto-content`
+(`format-html-title.ts:262-268`), so it loses the inherited `toc-left` grid
+and must carry the class itself for its `column-body` to align.
+
+## 5. Standalone `left` output shape
+
+```html
+<div id="quarto-content" class="page-columns page-rows-contents page-layout-article toc-left">
+  <div id="quarto-sidebar-toc-left" class="sidebar toc-left">
+    <nav id="TOC" role="doc-toc" class="toc-active" data-toc-expanded="…"> … </nav>
+  </div>
+  <div id="quarto-margin-sidebar" class="sidebar margin-sidebar"></div>
+  <main class="content" id="quarto-document-content"> … </main>
+</div>
+```
+
+No `collapse`/`sidebar-navigation`/`floating`/`#quarto-sidebar-glass` —
+those are website-only. The empty margin sidebar survives
+(`bootstrapHtmlFinalizer` only removes it when there is no TOC and no
+margin content, `format-html-bootstrap.ts:1030-1032`) and gets
+`zindex-bottom` when empty (`:1084-1091`).
+
+Other consumers of these ids:
+
+- `format-html-bootstrap.ts:857-865` — "Other Formats/Links" target chain:
+  `nav[role=doc-toc]` → `#quarto-sidebar-toc-left` → `#quarto-margin-sidebar`.
+- `src/resources/formats/html/quarto.js:53-58, 556-572` — runtime toggles:
+  `#quarto-margin-sidebar` → `quarto-toc-toggle`, `#quarto-sidebar` →
+  `quarto-sidebarnav-toggle`, `#quarto-sidebar-toc-left` →
+  `quarto-lefttoc-toggle`. (So in the website left case the TOC gets the
+  *sidebarnav* toggle, another behavioral difference between the paths.)
+
+## 6. Gotchas for a q2 implementation
+
+1. `toc-left` as a grid class only exists on the standalone path; websites
+   ride `body.floating`/`body.docked` grids. Two layout regimes, one option.
+2. `body` = absence of a target = plain undecorated list (no scroll-spy).
+3. `*-body` = clone `id="TOC-body"` with `.toc-actions` removed.
+4. `banner-header-class: toc-left` gated on `=== "left"` exactly.
+5. The article path emits `#quarto-margin-sidebar` unconditionally even for
+   `left`; downstream code (`getLinkTarget`, `zindex-bottom`,
+   `fullcontent`/`slimcontent` heuristics at
+   `format-html-bootstrap.ts:1036-1073`) depends on its presence.
diff --git a/claude-notes/plans/toc-location-investigation/repro/.gitignore b/claude-notes/plans/toc-location-investigation/repro/.gitignore
new file mode 100644
index 000000000..f6bae5814
--- /dev/null
+++ b/claude-notes/plans/toc-location-investigation/repro/.gitignore
@@ -0,0 +1,2 @@
+_site/
+.quarto/
diff --git a/claude-notes/plans/toc-location-investigation/repro/README.md b/claude-notes/plans/toc-location-investigation/repro/README.md
new file mode 100644
index 000000000..6c59c4071
--- /dev/null
+++ b/claude-notes/plans/toc-location-investigation/repro/README.md
@@ -0,0 +1,29 @@
+# toc-location: left repro (bd-e2kpwy7n)
+
+Local copy of the committed external repro from the Connect-docs port
+(`/Users/cscheid/repos/github/cscheid/q2-connect-docs/llms-info/repros/toc-location-left/`).
+
+Run:
+
+```bash
+cargo run --bin q2 -- render .
+```
+
+Observed at HEAD (2026-08-14, main after PR #530):
+
+- `grep -c 'id="quarto-sidebar"' _site/index.html` → `0`
+- `nav#TOC` renders inside `<div id="quarto-margin-sidebar" class="sidebar margin-sidebar">` (the right margin)
+
+Expected (Q1 1.10.15, same input — see `_site-q1/` in the external repro):
+
+- `nav#TOC` inside `<nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation floating overflow-auto">`
+- empty `<div id="quarto-margin-sidebar" class="sidebar margin-sidebar zindex-bottom">`
+- `<body class="floating quarto-light">`
+
+`_site/` is gitignored (generated).
+
+**Status:** fixed on branch `braid/bd-e2kpwy7n-toc-location`
+(2026-08-14) — q2 now renders `nav#TOC` inside a synthesized
+`nav#quarto-sidebar … sidebar-floating` with `body.floating`, matching
+the Q1 mechanism with q2's own class idiom. The "Observed at HEAD"
+section above records the pre-fix behavior.
diff --git a/claude-notes/plans/toc-location-investigation/repro/_quarto.yml b/claude-notes/plans/toc-location-investigation/repro/_quarto.yml
new file mode 100644
index 000000000..5f4d28898
--- /dev/null
+++ b/claude-notes/plans/toc-location-investigation/repro/_quarto.yml
@@ -0,0 +1,4 @@
+project:
+  type: website
+website:
+  title: "TOC Location Repro"
diff --git a/claude-notes/plans/toc-location-investigation/repro/index.qmd b/claude-notes/plans/toc-location-investigation/repro/index.qmd
new file mode 100644
index 000000000..464424c52
--- /dev/null
+++ b/claude-notes/plans/toc-location-investigation/repro/index.qmd
@@ -0,0 +1,13 @@
+---
+title: "Home"
+toc: true
+toc-location: left
+---
+
+## Alpha
+
+Text.
+
+## Beta
+
+Text.
diff --git a/crates/quarto-core/src/pipeline.rs b/crates/quarto-core/src/pipeline.rs
index 2330ce148..72067bca7 100644
--- a/crates/quarto-core/src/pipeline.rs
+++ b/crates/quarto-core/src/pipeline.rs
@@ -81,7 +81,7 @@ use crate::transforms::{
     ReferenceLinkDiagnosticsTransform, ResourceCollectorTransform, SectionizeTransform,
     ShortcodeResolveTransform, SidebarGenerateTransform, SidebarRenderTransform,
     TableBootstrapClassTransform, TheoremSugarTransform, TitleBannerTransform, TitleBlockTransform,
-    TocGenerateTransform, TocRenderTransform, WebsiteBootstrapIconsTransform,
+    TocGenerateTransform, TocLocationTransform, TocRenderTransform, WebsiteBootstrapIconsTransform,
     WebsiteCanonicalUrlTransform, WebsiteFaviconTransform, WebsiteTitlePrefixTransform,
 };
 
@@ -1413,6 +1413,12 @@ pub fn build_transform_pipeline(
         crate::project::listing::feed::ListingFeedLinkTransform::new(),
     ));
     pipeline.push(Box::new(TocRenderTransform::new()));
+    // Placement decision for the rendered TOC (bd-e2kpwy7n): must run
+    // after TocRenderTransform (it gates on `rendered.navigation.toc`)
+    // and before SidebarRenderTransform (which consumes the
+    // `toc-in-sidebar` directive to merge the TOC into
+    // `nav#quarto-sidebar` for website pages).
+    pipeline.push(Box::new(TocLocationTransform::new()));
     pipeline.push(Box::new(NavbarRenderTransform::new()));
     pipeline.push(Box::new(SidebarRenderTransform::new()));
     // Breadcrumbs derive from the resolved `navigation.sidebar`
diff --git a/crates/quarto-core/src/template.rs b/crates/quarto-core/src/template.rs
index a66a5bdd4..210b9a79e 100644
--- a/crates/quarto-core/src/template.rs
+++ b/crates/quarto-core/src/template.rs
@@ -152,6 +152,16 @@ $endfor$
 /// - `$rendered.navigation.toc-title$` - TOC title, rendered to HTML
 ///   (if set). Pre-rendered rather than read from `navigation.toc.title`
 ///   because the title carries inline markup — see `toc_render`.
+/// - `$rendered.navigation.toc-relocated$` / `toc-left` / `toc-body` -
+///   TOC placement flags written by `TocLocationTransform`
+///   (bd-e2kpwy7n). `toc-relocated` (any non-`right` placement)
+///   suppresses the right-margin TOC while keeping the
+///   categories-only margin shell; `toc-left` (standalone regime)
+///   emits `div#quarto-sidebar-toc-left` and puts the `toc-left`
+///   grid class on `#quarto-content`; `toc-body` emits the TOC
+///   inside `<main>` between the title block and the body. The
+///   website-left placement sets none of the template flags — there
+///   the TOC arrives merged inside `$rendered.navigation.sidebar$`.
 /// - `$rendered.navigation.navbar$` - Rendered navbar HTML (if navbar: set)
 /// - `$rendered.navigation.sidebar$` - Rendered sidebar HTML (if website.sidebar: set)
 /// - `$rendered.navigation.breadcrumbs$` - Rendered breadcrumb trail (consumed
@@ -210,18 +220,25 @@ $if(rendered.title-block-banner)$
 $title-block()$
 $endif$
 
-<div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-$page-layout$">
+<div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-$page-layout$$if(rendered.navigation.toc-left)$ toc-left$endif$">
 $if(rendered.navigation.sidebar)$
 $rendered.navigation.sidebar$
 $endif$
-$if(rendered.navigation.toc)$
+$if(rendered.navigation.toc-relocated)$
+$if(rendered.navigation.toc-left)$
+<div id="quarto-sidebar-toc-left" class="sidebar toc-left">
+$toc-block()$
+</div>
+$endif$
+$if(rendered.navigation.margin_categories)$
 <div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
-<nav id="TOC" role="doc-toc" class="toc-active">
-$if(rendered.navigation.toc-title)$
-<h2 id="toc-title">$rendered.navigation.toc-title$</h2>
+$rendered.navigation.margin_categories$
+</div>
 $endif$
-$rendered.navigation.toc$
-</nav>
+$else$
+$if(rendered.navigation.toc)$
+<div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
+$toc-block()$
 $if(rendered.navigation.margin_categories)$
 $rendered.navigation.margin_categories$
 $endif$
@@ -233,6 +250,7 @@ $rendered.navigation.margin_categories$
 </div>
 $endif$
 $endif$
+$endif$
 
 <main class="content$if(rendered.title-block-banner)$ quarto-banner-title-block$endif$" id="quarto-document-content">
 
@@ -241,6 +259,9 @@ $else$
 $title-block()$
 $endif$
 
+$if(rendered.navigation.toc-body)$
+$toc-block()$
+$endif$
 $body$
 
 $if(rendered.navigation.page_navigation)$
@@ -294,8 +315,9 @@ $endif$
 /// header and banner div are baked into the markup — Q1 gets them
 /// from its generic bootstrap grid DOM postprocessor, which Q2
 /// doesn't have. `quarto-template-params.banner-header-class` is
-/// ported verbatim but currently has no producer (Q1 sets `toc-left`
-/// from `toc-location`, which Q2 doesn't support yet).
+/// ported verbatim; its producer is `TocLocationTransform`, which
+/// sets `toc-left` when `toc-location: left` meets a banner
+/// (bd-e2kpwy7n).
 ///
 /// P6 (bd-vkiwhcny): `title-block-style: none` renders Q1's fallback
 /// — Pandoc's own plain title block
@@ -510,6 +532,24 @@ $endif$"#;
 /// by-author entry.
 pub const TITLE_META_AUTHOR_PARTIAL: &str = r##"$if(it.url)$<a href="$it.url$">$endif$$it.name.literal$$if(it.degrees)$, $for(it.degrees)$$it$$sep$, $endfor$$endif$$if(it.url)$</a>$endif$$if(it.email)$ <a href="mailto:$it.email$" class="quarto-title-author-email"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-envelope" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M0 4a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2zm2-1a1 1 0 0 0-1 1v.217l7 4.2 7-4.2V4a1 1 0 0 0-1-1zm13 2.383-4.708 2.825L15 11.105zm-.034 6.876-5.64-3.471L8 9.583l-1.326-.795-5.64 3.47A1 1 0 0 0 2 13h12a1 1 0 0 0 .966-.741M1 11.105l4.708-2.897L1 5.383z"/></svg></a>$endif$$if(it.orcid)$ <a href="https://orcid.org/$it.orcid$" class="quarto-title-author-orcid" aria-label="ORCID profile for $it.name.literal$"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#A6CE39" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M12 0C5.372 0 0 5.372 0 12s5.372 12 12 12 12-5.372 12-12S18.628 0 12 0zM7.369 4.378c.525 0 .947.431.947.947s-.422.947-.947.947a.95.95 0 0 1-.947-.947c0-.525.422-.947.947-.947zm-.722 3.038h1.444v10.041H6.647V7.416zm3.562 0h3.9c3.712 0 5.344 2.653 5.344 5.025 0 2.578-2.016 5.025-5.325 5.025h-3.919V7.416zm1.444 1.303v7.444h2.297c3.272 0 4.022-2.484 4.022-3.722 0-2.016-1.284-3.722-4.097-3.722h-2.222z"/></svg></a>$endif$"##;
 
+/// Built-in `toc-block` partial — the `nav#TOC` element (title +
+/// entries), shared by the three template-emitted TOC placements
+/// (right margin, standalone-left container, body — bd-e2kpwy7n) so
+/// they cannot drift apart.
+///
+/// The website-left placement does NOT go through this partial: there
+/// the TOC is merged into the `rendered.navigation.sidebar` fragment
+/// by `SidebarRenderTransform`, whose Rust-side twin of this markup is
+/// `toc_block_html` in `transforms/sidebar_render.rs` — keep the two
+/// in sync.
+pub const TOC_BLOCK_PARTIAL: &str = r#"<nav id="TOC" role="doc-toc" class="toc-active">
+$if(rendered.navigation.toc-title)$
+<h2 id="toc-title">$rendered.navigation.toc-title$</h2>
+$endif$
+$rendered.navigation.toc$
+</nav>
+"#;
+
 /// Resolver holding the built-in HTML template partials.
 ///
 /// Each partial is registered under both its bare name
@@ -522,6 +562,7 @@ pub fn builtin_html_partials() -> MemoryResolver {
         ("title-block", TITLE_BLOCK_PARTIAL),
         ("title-metadata", TITLE_METADATA_PARTIAL),
         ("_title-meta-author", TITLE_META_AUTHOR_PARTIAL),
+        ("toc-block", TOC_BLOCK_PARTIAL),
     ] {
         resolver.add(name, content);
         resolver.add(format!("{name}.html"), content);
@@ -2789,6 +2830,34 @@ mod tests {
         );
     }
 
+    /// bd-e2kpwy7n: a relocated TOC (`toc-location` left/body) must
+    /// not render in the right margin, but margin categories keep
+    /// their margin shell — the categories-only `$else$` shape.
+    #[test]
+    fn full_template_relocated_toc_keeps_categories_only_margin() {
+        let cat_html = r#"<h5 class="quarto-listing-category-title">Categories</h5>"#;
+        let mut meta = meta_with_navigation(Some("<ul><li>toc-entry</li></ul>"), Some(cat_html));
+        meta.insert_path(
+            &["rendered", "navigation", "toc-relocated"],
+            ConfigValue::new_bool(true, dummy_source_info()),
+        );
+        let html = render_full("<p>body</p>", &meta);
+        assert!(
+            html.contains(r#"<div id="quarto-margin-sidebar""#),
+            "categories keep their margin shell; got: {html}"
+        );
+        assert!(
+            html.contains(r#"class="quarto-listing-category-title""#),
+            "categories render in the margin; got: {html}"
+        );
+        assert!(
+            !html.contains("<nav id=\"TOC\""),
+            "a relocated TOC must not render in the margin (this test sets no \
+             placement flag, mirroring the website-left case where the TOC \
+             lives in the sidebar fragment); got: {html}"
+        );
+    }
+
     // L5 plan §"Tests" #37
     #[test]
     fn full_template_omits_margin_sidebar_when_neither_set() {
diff --git a/crates/quarto-core/src/transforms/mod.rs b/crates/quarto-core/src/transforms/mod.rs
index 0fd4f8f85..0a4df4523 100644
--- a/crates/quarto-core/src/transforms/mod.rs
+++ b/crates/quarto-core/src/transforms/mod.rs
@@ -80,6 +80,7 @@ mod theorem;
 mod title_banner;
 pub(crate) mod title_block;
 mod toc_generate;
+mod toc_location;
 mod toc_render;
 mod website_bootstrap_icons;
 mod website_canonical_url;
@@ -141,6 +142,7 @@ pub use theorem::TheoremSugarTransform;
 pub use title_banner::TitleBannerTransform;
 pub use title_block::TitleBlockTransform;
 pub use toc_generate::TocGenerateTransform;
+pub use toc_location::TocLocationTransform;
 pub use toc_render::TocRenderTransform;
 pub use website_bootstrap_icons::WebsiteBootstrapIconsTransform;
 pub use website_canonical_url::WebsiteCanonicalUrlTransform;
diff --git a/crates/quarto-core/src/transforms/sidebar_render.rs b/crates/quarto-core/src/transforms/sidebar_render.rs
index aaf30d2b7..a5b57d759 100644
--- a/crates/quarto-core/src/transforms/sidebar_render.rs
+++ b/crates/quarto-core/src/transforms/sidebar_render.rs
@@ -23,10 +23,22 @@
 //! format-agnostic `Sidebar` is committed to HTML output. See
 //! `claude-notes/plans/2026-04-24-websites-phase-2.md` §Decision 7/8.
 //!
+//! ## `toc-location: left` (bd-e2kpwy7n)
+//!
+//! When `TocLocationTransform` set the `rendered.navigation.toc-in-sidebar`
+//! directive (website regime), the rendered TOC block is appended
+//! inside `nav#quarto-sidebar` after the nav items; with no configured
+//! sidebar, a TOC-only floating sidebar is synthesized (and
+//! body-classes set to `nav-sidebar floating`) — Q1's `sidebar.ejs`
+//! with `sidebar === undefined`.
+//!
 //! ## Skip conditions
 //!
-//! - `sidebar: false` at the document level → neither output is set.
-//! - `navigation.sidebar` absent → neither output is set.
+//! - `sidebar: false` at the document level → the navigation sidebar
+//!   is not rendered (but a `toc-in-sidebar` TOC still synthesizes
+//!   its container, matching Q1's `nav.sidebar || navbarTocLeft`).
+//! - `navigation.sidebar` absent → neither output is set (unless
+//!   `toc-in-sidebar` synthesizes, as above).
 //! - `rendered.navigation.sidebar` already populated → the HTML
 //!   output is left alone (user override). The body-classes output
 //!   is computed independently with its own user-override check, so
@@ -35,7 +47,7 @@
 //!   body-classes output is left alone (user override).
 
 use quarto_error_reporting::DiagnosticMessage;
-use quarto_navigation::{Sidebar, SidebarEntry, render_html::sidebar_to_html};
+use quarto_navigation::{Sidebar, SidebarEntry, render_html::sidebar_to_html_with_appended};
 use quarto_pandoc_types::config_value::ConfigValue;
 use quarto_pandoc_types::pandoc::Pandoc;
 use quarto_source_map::{By, SourceInfo};
@@ -73,11 +85,37 @@ impl AstTransform for SidebarRenderTransform {
     }
 
     async fn transform(&self, ast: &mut Pandoc, ctx: &mut RenderContext) -> Result<()> {
-        if is_feature_disabled(&ast.meta, "sidebar") {
-            return Ok(());
-        }
+        // bd-e2kpwy7n: the `toc-in-sidebar` directive written by
+        // `TocLocationTransform` (website regime, `toc-location:
+        // left`). When set, the rendered TOC block is appended inside
+        // `nav#quarto-sidebar` — after the nav items when a sidebar is
+        // configured (Q1's `sidebar.ejs` merge order), or as the sole
+        // content of a synthesized floating sidebar when none is.
+        let toc_block = if ast
+            .meta
+            .get_path(&["rendered", "navigation", "toc-in-sidebar"])
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false)
+        {
+            toc_block_html(&ast.meta)
+        } else {
+            None
+        };
+
+        // `sidebar: false` disables the *navigation* sidebar, not the
+        // left TOC: Q1's `nav-before-body.ejs` emits the sidebar
+        // partial for `nav.sidebar || navbarTocLeft`, so a disabled
+        // sidebar still synthesizes the TOC-only container.
+        let sidebar_cv = if is_feature_disabled(&ast.meta, "sidebar") {
+            None
+        } else {
+            ast.meta.get_path(&["navigation", "sidebar"])
+        };
 
-        let Some(sidebar_cv) = ast.meta.get_path(&["navigation", "sidebar"]) else {
+        let Some(sidebar_cv) = sidebar_cv else {
+            if let Some(toc_block) = toc_block {
+                synthesize_toc_sidebar(ast, ctx, &toc_block);
+            }
             return Ok(());
         };
 
@@ -137,7 +175,7 @@ impl AstTransform for SidebarRenderTransform {
             .resource_resolver
             .as_ref()
             .map_or_else(|| "./".to_string(), |r| r.page_url_for_site_root_dir());
-        let html = sidebar_to_html(&sidebar, &home_url);
+        let html = sidebar_to_html_with_appended(&sidebar, &home_url, toc_block.as_deref());
 
         ast.meta.insert_path(
             &["rendered", "navigation", "sidebar"],
@@ -148,6 +186,70 @@ impl AstTransform for SidebarRenderTransform {
     }
 }
 
+/// The Rust twin of the template's `toc-block` partial
+/// ([`crate::template::TOC_BLOCK_PARTIAL`] — keep the markup in sync):
+/// the full `nav#TOC` element composed from the rendered TOC metadata.
+/// Needed here because the website-left TOC lives inside the
+/// `rendered.navigation.sidebar` fragment, which the template emits
+/// opaquely.
+fn toc_block_html(meta: &ConfigValue) -> Option<String> {
+    let toc = meta
+        .get_path(&["rendered", "navigation", "toc"])?
+        .as_plain_text()?;
+    if toc.is_empty() {
+        return None;
+    }
+    let mut html = String::from("<nav id=\"TOC\" role=\"doc-toc\" class=\"toc-active\">\n");
+    if let Some(title) = meta
+        .get_path(&["rendered", "navigation", "toc-title"])
+        .and_then(|v| v.as_plain_text())
+    {
+        html.push_str(&format!("<h2 id=\"toc-title\">{title}</h2>\n"));
+    }
+    html.push_str(&toc);
+    html.push_str("</nav>\n");
+    Some(html)
+}
+
+/// Synthesize the TOC-only floating sidebar for a website page with
+/// `toc-location: left` and no configured navigation sidebar — Q1's
+/// `sidebar.ejs` rendered with `sidebar === undefined`, where the
+/// style ternary falls back to `floating` and the wrapper holds only
+/// the TOC target.
+fn synthesize_toc_sidebar(ast: &mut Pandoc, ctx: &mut RenderContext, toc_block: &str) {
+    if !ast
+        .meta
+        .contains_path(&["rendered", "navigation", "body-classes"])
+    {
+        ast.meta.insert_path(
+            &["rendered", "navigation", "body-classes"],
+            ConfigValue::new_string(
+                "nav-sidebar floating",
+                SourceInfo::generated(By::programmatic_config()),
+            ),
+        );
+    }
+
+    if ast
+        .meta
+        .contains_path(&["rendered", "navigation", "sidebar"])
+    {
+        return;
+    }
+
+    let mut sidebar = Sidebar::with_defaults();
+    sidebar.style = quarto_navigation::SidebarStyle::Floating;
+    let home_url = ctx
+        .resource_resolver
+        .as_ref()
+        .map_or_else(|| "./".to_string(), |r| r.page_url_for_site_root_dir());
+    let html = sidebar_to_html_with_appended(&sidebar, &home_url, Some(toc_block));
+    ast.meta.insert_path(
+        &["rendered", "navigation", "sidebar"],
+        ConfigValue::new_string(&html, SourceInfo::generated(By::programmatic_config())),
+    );
+}
+
 /// Walk the sidebar, rewriting each entry's href from source-path to
 /// output-href via the project index, and relativizing the result
 /// to the current page via the resolver. See bd-swpy /
diff --git a/crates/quarto-core/src/transforms/title_banner.rs b/crates/quarto-core/src/transforms/title_banner.rs
index e39a4533f..4088f60be 100644
--- a/crates/quarto-core/src/transforms/title_banner.rs
+++ b/crates/quarto-core/src/transforms/title_banner.rs
@@ -35,12 +35,14 @@
 //!   output tree at the URL the generated style references (the
 //!   `ResourceCollectorTransform` pattern).
 //!
-//! Deliberately not ported (deviations documented in the epic plan):
+//! Deliberately not ported (deviation documented in the epic plan):
 //! `#quarto-header.quarto-banner` (Q2's navbar has no `#quarto-header`
 //! wrapper, and the class's only Q1 consumer styles the website
-//! secondary nav, which Q2 doesn't have) and the `toc-left`
-//! `banner-header-class` producer (Q2 has no `toc-location` option
-//! yet; the template hook is in place for when it lands).
+//! secondary nav, which Q2 doesn't have). The `toc-left`
+//! `banner-header-class` producer lives in
+//! [`TocLocationTransform`](super::TocLocationTransform), not here —
+//! it needs the normalized `toc-location`, which is a
+//! Navigation-phase concern (bd-e2kpwy7n).
 //!
 //! Plan: `claude-notes/plans/2026-07-15-html-title-block-parity.md`
 //! (Phase 5).
diff --git a/crates/quarto-core/src/transforms/toc_location.rs b/crates/quarto-core/src/transforms/toc_location.rs
new file mode 100644
index 000000000..2b26a37fd
--- /dev/null
+++ b/crates/quarto-core/src/transforms/toc_location.rs
@@ -0,0 +1,246 @@
+/*
+ * toc_location.rs
+ * Copyright (c) 2026 Posit, PBC
+ *
+ * Transform that normalizes `toc-location` and publishes placement
+ * directives for the template and the sidebar renderer.
+ */
+
+//! `toc-location` normalization (bd-e2kpwy7n).
+//!
+//! Quarto 1 implements `toc-location` with a DOM postprocessor that
+//! moves `nav#TOC` into a placeholder emitted by one of two template
+//! paths (see
+//! `claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md`).
+//! Q2 has no DOM postprocessor stage, so this transform decides the
+//! placement up front and publishes it as metadata; the template and
+//! [`SidebarRenderTransform`](super::SidebarRenderTransform) then emit
+//! the right markup the first time.
+//!
+//! ## Outputs
+//!
+//! All under `rendered.navigation` unless noted; written only when a
+//! rendered TOC exists (`rendered.navigation.toc`, produced by
+//! [`TocRenderTransform`](super::TocRenderTransform) — this transform
+//! must run after it and before `SidebarRenderTransform`):
+//!
+//! - **`toc-location`** — the normalized value (`"left"` | `"right"` |
+//!   `"body"`). The single source of truth for downstream consumers
+//!   (the preview follow-up bd-tqijrhsu reads this).
+//! - **`toc-relocated`** (bool) — set when the location is not
+//!   `right`; the template suppresses the right-margin TOC region on
+//!   it (margin categories keep their margin shell).
+//! - **`toc-left`** (bool) — standalone regime only: the template
+//!   emits `div#quarto-sidebar-toc-left.sidebar.toc-left` and puts the
+//!   `toc-left` grid class on `#quarto-content`
+//!   (`.page-columns.toc-left` SCSS, gated on
+//!   `body:not(.floating):not(.docked)`).
+//! - **`toc-in-sidebar`** (bool) — website regime only: consumed by
+//!   `SidebarRenderTransform`, which merges the TOC into
+//!   `nav#quarto-sidebar` (appending after nav items, or synthesizing
+//!   a floating sidebar when none is configured). Not read by the
+//!   template.
+//! - **`toc-body`** (bool) — the template emits the TOC inside
+//!   `<main>`, between the title block and the body.
+//! - **`quarto-template-params.banner-header-class`** = `"toc-left"`
+//!   when the location is `left` and a banner title block is active
+//!   (`rendered.title-block-banner`, written by the
+//!   Normalization-phase
+//!   [`TitleBannerTransform`](super::TitleBannerTransform)) — the
+//!   previously-inert hook in
+//!   [`TITLE_BLOCK_PARTIAL`](crate::template::TITLE_BLOCK_PARTIAL).
+//!
+//! ## Regimes
+//!
+//! Mirroring Q1's two layouts (design decision 2): pages of a
+//! [`ProjectKind::Website`] project use the website regime (TOC inside
+//! `nav#quarto-sidebar`, `body.floating` grid); everything else —
+//! standalone documents, default projects, and for now book/manuscript
+//! projects — uses the standalone regime (`toc-left` grid).
+//!
+//! ## Values
+//!
+//! `left`, `right` (default), `body` are implemented. `left-body` /
+//! `right-body` warn (Q-13-8) and fall back to their sidebar half
+//! until bd-jclcm0in lands; unknown values warn and default to
+//! `right`. Warnings are only emitted when a TOC actually rendered —
+//! without one the option is inert, and Q1 ignores it entirely.
+//!
+//! Plan: `claude-notes/plans/2026-08-14-toc-location.md`.
+
+use quarto_error_reporting::DiagnosticMessageBuilder;
+use quarto_pandoc_types::ConfigValue;
+use quarto_pandoc_types::pandoc::Pandoc;
+use quarto_source_map::{By, SourceInfo};
+
+use crate::Result;
+use crate::project::ProjectKind;
+use crate::render::RenderContext;
+use crate::transform::{AstTransform, TransformPhase};
+
+/// The normalized TOC placement.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TocLocation {
+    Left,
+    Right,
+    Body,
+}
+
+impl TocLocation {
+    fn as_str(self) -> &'static str {
+        match self {
+            TocLocation::Left => "left",
+            TocLocation::Right => "right",
+            TocLocation::Body => "body",
+        }
+    }
+}
+
+pub struct TocLocationTransform;
+
+impl TocLocationTransform {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for TocLocationTransform {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait::async_trait(?Send)]
+impl AstTransform for TocLocationTransform {
+    fn name(&self) -> &str {
+        "toc-location"
+    }
+
+    fn phase(&self) -> TransformPhase {
+        TransformPhase::Navigation
+    }
+
+    async fn transform(&self, ast: &mut Pandoc, ctx: &mut RenderContext) -> Result<()> {
+        // Without a rendered TOC the option is inert (Q1 parity: the
+        // placeholder is only emitted when `hasTableOfContents`).
+        if !ast.meta.contains_path(&["rendered", "navigation", "toc"]) {
+            return Ok(());
+        }
+
+        // A pre-populated `rendered.navigation.toc-location` is a user
+        // override (the `rendered.*` convention shared with toc/sidebar
+        // HTML): normalize from it, and leave the key itself alone.
+        let (raw, preset) = match ast
+            .meta
+            .get_path(&["rendered", "navigation", "toc-location"])
+        {
+            Some(v) => (Some((v.as_plain_text(), v.source_info.clone())), true),
+            None => (
+                ast.meta
+                    .get("toc-location")
+                    .map(|v| (v.as_plain_text(), v.source_info.clone())),
+                false,
+            ),
+        };
+
+        let location = match raw {
+            None => TocLocation::Right,
+            Some((text, source_info)) => {
+                let text = text.unwrap_or_default();
+                match text.as_str() {
+                    "left" => TocLocation::Left,
+                    "right" => TocLocation::Right,
+                    "body" => TocLocation::Body,
+                    "left-body" | "right-body" => {
+                        let fallback = if text == "left-body" {
+                            TocLocation::Left
+                        } else {
+                            TocLocation::Right
+                        };
+                        ctx.diagnostics.push(
+                            DiagnosticMessageBuilder::warning(format!(
+                                "`toc-location: {text}` is not supported yet"
+                            ))
+                            .with_code("Q-13-8")
+                            .problem(format!(
+                                "The `{text}` value (a sidebar TOC plus a copy in the body) \
+                                 is not implemented yet. Falling back to `toc-location: {}`.",
+                                fallback.as_str()
+                            ))
+                            .with_location(source_info)
+                            .build(),
+                        );
+                        fallback
+                    }
+                    other => {
+                        ctx.diagnostics.push(
+                            DiagnosticMessageBuilder::warning(format!(
+                                "Unknown `toc-location` value `{other}`"
+                            ))
+                            .with_code("Q-13-8")
+                            .problem(
+                                "Supported values are `left`, `right`, and `body`. \
+                                 Using the default `toc-location: right`.",
+                            )
+                            .with_location(source_info)
+                            .build(),
+                        );
+                        TocLocation::Right
+                    }
+                }
+            }
+        };
+
+        if !preset {
+            ast.meta.insert_path(
+                &["rendered", "navigation", "toc-location"],
+                ConfigValue::new_string(location.as_str(), gen_si()),
+            );
+        }
+
+        let website = ctx.project.project_kind() == ProjectKind::Website;
+        match location {
+            TocLocation::Right => {}
+            TocLocation::Left => {
+                set_flag(ast, "toc-relocated");
+                if website {
+                    set_flag(ast, "toc-in-sidebar");
+                } else {
+                    set_flag(ast, "toc-left");
+                }
+                // Fire the banner header-class hook (Q1:
+                // `format-html-title.ts:169-175`) — the banner header
+                // sits outside `#quarto-content`, so it must carry the
+                // grid class itself to line up with the shifted body
+                // column.
+                if ast.meta.contains_path(&["rendered", "title-block-banner"])
+                    && !ast
+                        .meta
+                        .contains_path(&["quarto-template-params", "banner-header-class"])
+                {
+                    ast.meta.insert_path(
+                        &["quarto-template-params", "banner-header-class"],
+                        ConfigValue::new_string("toc-left", gen_si()),
+                    );
+                }
+            }
+            TocLocation::Body => {
+                set_flag(ast, "toc-relocated");
+                set_flag(ast, "toc-body");
+            }
+        }
+
+        Ok(())
+    }
+}
+
+fn set_flag(ast: &mut Pandoc, key: &str) {
+    ast.meta.insert_path(
+        &["rendered", "navigation", key],
+        ConfigValue::new_bool(true, gen_si()),
+    );
+}
+
+fn gen_si() -> SourceInfo {
+    SourceInfo::generated(By::programmatic_config())
+}
diff --git a/crates/quarto-core/tests/integration/main.rs b/crates/quarto-core/tests/integration/main.rs
index fd63a9260..8a443f5d5 100644
--- a/crates/quarto-core/tests/integration/main.rs
+++ b/crates/quarto-core/tests/integration/main.rs
@@ -66,6 +66,7 @@ pub mod shortcode_text_contexts;
 pub mod sidebar_pipeline;
 pub mod theme_light_dark;
 pub mod title_block_pipeline;
+pub mod toc_location;
 pub mod toc_markup;
 pub mod toc_title_context;
 pub mod video_shortcode_preview;
diff --git a/crates/quarto-core/tests/integration/toc_location.rs b/crates/quarto-core/tests/integration/toc_location.rs
new file mode 100644
index 000000000..2a32a5ed0
--- /dev/null
+++ b/crates/quarto-core/tests/integration/toc_location.rs
@@ -0,0 +1,487 @@
+/*
+ * toc_location.rs
+ * Copyright (c) 2026 Posit, PBC
+ *
+ * bd-e2kpwy7n: `toc-location` option (left/right/body).
+ */
+
+//! End-to-end coverage for TOC placement (`toc-location`).
+//!
+//! Every test drives the real render path — `ProjectPipeline` for
+//! website fixtures, `render_to_file` for standalone documents — and
+//! inspects the HTML written to disk. The expected shapes are the two
+//! Q1 layout regimes mapped in
+//! `claude-notes/plans/toc-location-investigation/q1-mechanism-notes.md`:
+//!
+//! - **Standalone `left`**: `#quarto-content` gains the `toc-left` grid
+//!   class and a `div#quarto-sidebar-toc-left.sidebar.toc-left` holds
+//!   the TOC (`body` does NOT ride the floating/docked grids).
+//! - **Website `left`**: the TOC merges into `nav#quarto-sidebar`
+//!   (synthesized with the floating style when no sidebar is
+//!   configured) and the body rides the `floating` grid.
+//! - **`body`**: the TOC renders inside `main#quarto-document-content`,
+//!   keeping q2's decorated markup (deliberate deviation from Q1's
+//!   plain list — design decision 4).
+//! - **`right` / unset**: unchanged — TOC in `#quarto-margin-sidebar`.
+//!
+//! Deliberate q2 deviation (design decision 5): when the TOC moves out
+//! of the right margin, q2 omits `#quarto-margin-sidebar` entirely
+//! instead of emitting Q1's empty `zindex-bottom` shell.
+//!
+//! Plan: `claude-notes/plans/2026-08-14-toc-location.md`.
+
+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, project_type_for};
+use quarto_core::render_to_file::{RenderToFileOptions, render_to_file};
+use quarto_error_reporting::DiagnosticMessage;
+use quarto_system_runtime::{NativeRuntime, SystemRuntime};
+
+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 canonical(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|_| path.to_path_buf())
+}
+
+/// Render a website project fixture through the real `ProjectPipeline`
+/// and return the rendered `index.html`.
+fn render_website(fixture: impl FnOnce(&Path)) -> String {
+    let temp = TempDir::new().unwrap();
+    let project_dir = canonical(temp.path());
+    fixture(&project_dir);
+
+    let runtime: Arc<dyn SystemRuntime> = Arc::new(NativeRuntime::new());
+    let mut project = ProjectContext::discover(&project_dir, runtime.as_ref()).expect("discover");
+    assert!(!project.is_single_file, "expected a website project");
+    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 run");
+    assert!(
+        summary.pass1_failures.is_empty() && summary.pass2_failures.is_empty(),
+        "unexpected failures: pass1={:?} pass2={:?}",
+        summary
+            .pass1_failures
+            .iter()
+            .map(|f| (&f.input, &f.error))
+            .collect::<Vec<_>>(),
+        summary
+            .pass2_failures
+            .iter()
+            .map(|f| (&f.input, &f.error))
+            .collect::<Vec<_>>()
+    );
+
+    let out = project.output_dir.clone();
+    std::fs::read_to_string(out.join("index.html")).expect("rendered index.html")
+}
+
+/// The single-page website fixture: no configured sidebar, `toc: true`,
+/// and the given extra front-matter lines.
+fn website_single_page(extra_frontmatter: &str) -> impl FnOnce(&Path) + '_ {
+    move |project_dir: &Path| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            "project:\n  type: website\nwebsite:\n  title: \"TOC location test\"\n",
+        );
+        write(
+            &project_dir.join("index.qmd"),
+            &format!(
+                "---\ntitle: \"Home\"\ntoc: true\n{extra_frontmatter}---\n\n\
+                 ## Alpha\n\nText.\n\n## Beta\n\nText.\n"
+            ),
+        );
+    }
+}
+
+/// Render a standalone document (no `_quarto.yml`) through the real
+/// single-file CLI path (`render_to_file`). Returns the rendered HTML
+/// and the collected diagnostics.
+fn render_standalone(frontmatter: &str) -> (String, Vec<DiagnosticMessage>) {
+    let temp = TempDir::new().unwrap();
+    let doc_dir = canonical(temp.path());
+    let input = doc_dir.join("doc.qmd");
+    write(
+        &input,
+        &format!(
+            "---\ntitle: \"Doc\"\ntoc: true\n{frontmatter}---\n\n\
+             ## Alpha\n\nText.\n\n## Beta\n\nText.\n"
+        ),
+    );
+
+    let runtime: Arc<dyn SystemRuntime> = Arc::new(NativeRuntime::new());
+    let options = RenderToFileOptions::default();
+    let result = render_to_file(&input, "html", &options, runtime).expect("render");
+    let html = std::fs::read_to_string(&result.output_path).expect("rendered doc.html");
+    (html, result.render_output.diagnostics)
+}
+
+// ---------------------------------------------------------------------
+// HTML region helpers
+// ---------------------------------------------------------------------
+
+/// Extract the element region starting at `open_needle`, balancing
+/// nested `<tag`/`</tag>` pairs so containers holding a nested element
+/// of the same tag (e.g. `nav#quarto-sidebar` around `nav#TOC`) close
+/// at the right spot.
+fn balanced_region(html: &str, open_needle: &str, tag: &str) -> String {
+    let start = html
+        .find(open_needle)
+        .unwrap_or_else(|| panic!("no `{open_needle}` in rendered HTML:\n{html}"));
+    let open_tag = format!("<{tag}");
+    let close_tag = format!("</{tag}>");
+    let mut depth = 0usize;
+    let mut pos = start;
+    loop {
+        let next_open = html[pos + 1..].find(&open_tag).map(|i| pos + 1 + i);
+        let next_close = html[pos + 1..].find(&close_tag).map(|i| pos + 1 + i);
+        match (next_open, next_close) {
+            (Some(o), Some(c)) if o < c => {
+                depth += 1;
+                pos = o;
+            }
+            (_, Some(c)) => {
+                if depth == 0 {
+                    return html[start..c + close_tag.len()].to_string();
+                }
+                depth -= 1;
+                pos = c;
+            }
+            _ => panic!("unterminated `{open_needle}` region:\n{html}"),
+        }
+    }
+}
+
+/// The class attribute of the first tag matching `open_needle`.
+fn class_attr(html: &str, open_needle: &str) -> String {
+    let start = html
+        .find(open_needle)
+        .unwrap_or_else(|| panic!("no `{open_needle}` in rendered HTML:\n{html}"));
+    let tag_end = html[start..].find('>').expect("unterminated tag") + start;
+    let tag = &html[start..tag_end];
+    let class_start = tag.find("class=\"").map(|i| i + "class=\"".len());
+    match class_start {
+        Some(cs) => {
+            let rest = &tag[cs..];
+            let end = rest.find('"').expect("unterminated class attribute");
+            rest[..end].to_string()
+        }
+        None => String::new(),
+    }
+}
+
+fn has_class(html: &str, open_needle: &str, class: &str) -> bool {
+    class_attr(html, open_needle)
+        .split_whitespace()
+        .any(|c| c == class)
+}
+
+fn body_classes(html: &str) -> String {
+    class_attr(html, "<body")
+}
+
+fn diagnostics_mention(diags: &[DiagnosticMessage], needle: &str) -> bool {
+    diags.iter().any(|d| format!("{d:?}").contains(needle))
+}
+
+// ---------------------------------------------------------------------
+// Website `left`
+// ---------------------------------------------------------------------
+
+/// The Connect-docs repro shape: a website page with `toc-location:
+/// left` and no configured sidebar gets a synthesized floating
+/// `nav#quarto-sidebar` holding the TOC; the right margin sidebar is
+/// omitted entirely (decision 5).
+#[test]
+fn website_left_without_sidebar_synthesizes_floating_sidebar() {
+    let html = render_website(website_single_page("toc-location: left\n"));
+
+    let sidebar = balanced_region(&html, "<nav id=\"quarto-sidebar\"", "nav");
+    assert!(
+        sidebar.contains("<nav id=\"TOC\""),
+        "the TOC must live inside nav#quarto-sidebar; sidebar region:\n{sidebar}"
+    );
+    assert!(
+        has_class(&html, "<nav id=\"quarto-sidebar\"", "sidebar-floating"),
+        "a synthesized sidebar uses the floating style; got classes: {:?}",
+        class_attr(&html, "<nav id=\"quarto-sidebar\"")
+    );
+    assert!(
+        body_classes(&html)
+            .split_whitespace()
+            .any(|c| c == "floating"),
+        "the body must ride the floating grid; got: {:?}",
+        body_classes(&html)
+    );
+    assert!(
+        !html.contains("id=\"quarto-margin-sidebar\""),
+        "no empty right-margin shell when the TOC moves left (decision 5)"
+    );
+}
+
+/// A configured website sidebar and `toc-location: left` share one
+/// `nav#quarto-sidebar`: nav items first, TOC appended after (Q1's
+/// sidebar.ejs merge order).
+#[test]
+fn website_left_with_sidebar_merges_toc_after_nav_items() {
+    let html = render_website(|project_dir| {
+        write(
+            &project_dir.join("_quarto.yml"),
+            "project:\n  type: website\nwebsite:\n  title: \"TOC location test\"\n  \
+             sidebar:\n    contents:\n      - index.qmd\n      - about.qmd\n",
+        );
+        write(
+            &project_dir.join("index.qmd"),
+            "---\ntitle: \"Home\"\ntoc: true\ntoc-location: left\n---\n\n\
+             ## Alpha\n\nText.\n\n## Beta\n\nText.\n",
+        );
+        write(
+            &project_dir.join("about.qmd"),
+            "---\ntitle: \"About\"\n---\n\nAbout.\n",
+        );
+    });
+
+    assert_eq!(
+        html.matches("id=\"quarto-sidebar\"").count(),
+        1,
+        "exactly one sidebar container — the TOC merges, it does not add a second"
+    );
+    let sidebar = balanced_region(&html, "<nav id=\"quarto-sidebar\"", "nav");
+    let nav_item = sidebar
+        .find("about.html")
+        .expect("sidebar nav items must render before the TOC");
+    let toc = sidebar
+        .find("<nav id=\"TOC\"")
+        .expect("the TOC must live inside nav#quarto-sidebar");
+    assert!(
+        nav_item < toc,
+        "nav items come first, TOC after (Q1 merge order); sidebar region:\n{sidebar}"
+    );
+    assert!(
+        !html.contains("id=\"quarto-margin-sidebar\""),
+        "no empty right-margin shell when the TOC moves left (decision 5)"
+    );
+}
+
+// ---------------------------------------------------------------------
+// Standalone `left`
+// ---------------------------------------------------------------------
+
+/// A standalone document with `toc-location: left` uses the toc-left
+/// grid: `toc-left` on `#quarto-content`, the TOC inside
+/// `div#quarto-sidebar-toc-left.sidebar.toc-left`, and a body that does
+/// NOT ride the floating/docked grids (the `.page-columns.toc-left`
+/// SCSS is gated on `body:not(.floating):not(.docked)`).
+#[test]
+fn standalone_left_uses_toc_left_grid() {
+    let (html, _) = render_standalone("toc-location: left\n");
+
+    assert!(
+        has_class(&html, "<div id=\"quarto-content\"", "toc-left"),
+        "#quarto-content must carry the toc-left grid class; got: {:?}",
+        class_attr(&html, "<div id=\"quarto-content\"")
+    );
+    let container = balanced_region(&html, "<div id=\"quarto-sidebar-toc-left\"", "div");
+    assert!(
+        container.contains("<nav id=\"TOC\""),
+        "the TOC must live inside #quarto-sidebar-toc-left; region:\n{container}"
+    );
+    assert!(
+        has_class(&html, "<div id=\"quarto-sidebar-toc-left\"", "sidebar")
+            && has_class(&html, "<div id=\"quarto-sidebar-toc-left\"", "toc-left"),
+        "the container needs .sidebar.toc-left for the grid placement rules; got: {:?}",
+        class_attr(&html, "<div id=\"quarto-sidebar-toc-left\"")
+    );
+    let body = body_classes(&html);
+    assert!(
+        !body
+            .split_whitespace()
+            .any(|c| c == "floating" || c == "docked"),
+        "standalone left must not ride the website sidebar grids; body classes: {body:?}"
+    );
+    assert!(
+        !html.contains("id=\"quarto-margin-sidebar\""),
+        "no empty right-margin shell when the TOC moves left (decision 5)"
+    );
+}
+
+// ---------------------------------------------------------------------
+// `body`
+// ---------------------------------------------------------------------
+
+/// `toc-location: body` renders the TOC inside the main content
+/// column. q2 keeps the decorated markup (`data-scroll-target`) —
+/// deliberate deviation from Q1's plain list (decision 4: scroll-spy
+/// support is coming and the attributes are inert without it).
+#[test]
+fn body_location_renders_toc_in_main() {
+    let (html, _) = render_standalone("toc-location: body\n");
+
+    let main = balanced_region(&html, "<main class=", "main");
+    assert!(
+        main.contains("<nav id=\"TOC\""),
+        "the TOC must render inside <main>; main region:\n{main}"
+    );
+    assert!(
+        main.contains("data-scroll-target="),
+        "body TOC keeps q2's decorated markup (decision 4)"
+    );
+    assert!(
+        !html.contains("id=\"quarto-margin-sidebar\""),
+        "no right-margin TOC when location is body"
+    );
+    assert!(
+        !html.contains("id=\"quarto-sidebar-toc-left\"") && !html.contains("id=\"quarto-sidebar\""),
+        "no sidebar containers when location is body"
+    );
+}
+
+// ---------------------------------------------------------------------
+// `right` / default
+// ---------------------------------------------------------------------
+
+/// Explicit `toc-location: right` must be exactly the default
+/// placement — the option landing must not perturb the existing shape.
+#[test]
+fn right_explicit_matches_default_placement() {
+    let (default_html, _) = render_standalone("");
+    let (right_html, _) = render_standalone("toc-location: right\n");
+
+    let default_margin = balanced_region(&default_html, "<div id=\"quarto-margin-sidebar\"", "div");
+    let right_margin = balanced_region(&right_html, "<div id=\"quarto-margin-sidebar\"", "div");
+    assert!(
+        default_margin.contains("<nav id=\"TOC\""),
+        "default: TOC in the right margin sidebar"
+    );
+    assert_eq!(
+        default_margin, right_margin,
+        "explicit `right` must be byte-identical to the default margin region"
+    );
+}
+
+// ---------------------------------------------------------------------
+// Banner interaction
+// ---------------------------------------------------------------------
+
+/// Banner mode + `toc-location: left` fires the (previously inert)
+/// `banner-header-class` hook: `#title-block-header` carries `toc-left`
+/// so the relocated banner header lines up with the shifted body
+/// column.
+#[test]
+fn banner_left_adds_toc_left_header_class() {
+    let (html, _) = render_standalone("title-block-banner: true\ntoc-location: left\n");
+
+    assert!(
+        has_class(&html, "<header id=\"title-block-header\"", "toc-left"),
+        "banner header must carry toc-left; got classes: {:?}",
+        class_attr(&html, "<header id=\"title-block-header\"")
+    );
+}
+
+/// Control: banner mode without `toc-location: left` must NOT get the
+/// class.
+#[test]
+fn banner_without_left_has_no_toc_left_header_class() {
+    let (html, _) = render_standalone("title-block-banner: true\n");
+
+    assert!(
+        !has_class(&html, "<header id=\"title-block-header\"", "toc-left"),
+        "banner header must not carry toc-left when the TOC is on the right; got: {:?}",
+        class_attr(&html, "<header id=\"title-block-header\"")
+    );
+}
+
+// ---------------------------------------------------------------------
+// `*-body` fallback and unknown values
+// ---------------------------------------------------------------------
+
+/// `left-body` warns and falls back to `left` (the body clone is
+/// bd-jclcm0in).
+#[test]
+fn left_body_warns_and_falls_back_to_left() {
+    let (html, diags) = render_standalone("toc-location: left-body\n");
+
+    assert!(
+        diagnostics_mention(&diags, "toc-location"),
+        "a fallback warning naming toc-location must be emitted; got: {diags:?}"
+    );
+    let container = balanced_region(&html, "<div id=\"quarto-sidebar-toc-left\"", "div");
+    assert!(
+        container.contains("<nav id=\"TOC\""),
+        "left-body places like left until bd-jclcm0in lands"
+    );
+}
+
+/// `right-body` warns and falls back to `right`.
+#[test]
+fn right_body_warns_and_falls_back_to_right() {
+    let (html, diags) = render_standalone("toc-location: right-body\n");
+
+    assert!(
+        diagnostics_mention(&diags, "toc-location"),
+        "a fallback warning naming toc-location must be emitted; got: {diags:?}"
+    );
+    let margin = balanced_region(&html, "<div id=\"quarto-margin-sidebar\"", "div");
+    assert!(
+        margin.contains("<nav id=\"TOC\""),
+        "right-body places like right until bd-jclcm0in lands"
+    );
+}
+
+/// An unknown value warns and defaults to `right`.
+#[test]
+fn unknown_location_warns_and_defaults_to_right() {
+    let (html, diags) = render_standalone("toc-location: sideways\n");
+
+    assert!(
+        diagnostics_mention(&diags, "toc-location"),
+        "an unknown-value warning naming toc-location must be emitted; got: {diags:?}"
+    );
+    let margin = balanced_region(&html, "<div id=\"quarto-margin-sidebar\"", "div");
+    assert!(
+        margin.contains("<nav id=\"TOC\""),
+        "unknown values keep the default right placement"
+    );
+}
+
+// ---------------------------------------------------------------------
+// Website `left` in banner mode keeps working end-to-end
+// ---------------------------------------------------------------------
+
+/// The website regime and the banner producer compose: a website page
+/// with a banner and `toc-location: left` gets both the sidebar merge
+/// and the header class.
+#[test]
+fn website_banner_left_composes() {
+    let html = render_website(website_single_page(
+        "toc-location: left\ntitle-block-banner: true\n",
+    ));
+
+    let sidebar = balanced_region(&html, "<nav id=\"quarto-sidebar\"", "nav");
+    assert!(
+        sidebar.contains("<nav id=\"TOC\""),
+        "TOC inside the sidebar in banner mode too; region:\n{sidebar}"
+    );
+    assert!(
+        has_class(&html, "<header id=\"title-block-header\"", "toc-left"),
+        "banner header carries toc-left; got: {:?}",
+        class_attr(&html, "<header id=\"title-block-header\"")
+    );
+}
diff --git a/crates/quarto-error-catalog/error_catalog.json b/crates/quarto-error-catalog/error_catalog.json
index e54f50e89..d0da0c736 100644
--- a/crates/quarto-error-catalog/error_catalog.json
+++ b/crates/quarto-error-catalog/error_catalog.json
@@ -1440,5 +1440,12 @@
     "message_template": "`website.llms-txt: true` wants to write a file that already exists in the output directory and was not generated by llms-txt. Overwriting it silently would destroy that content.",
     "docs_url": "https://quarto.org/docs/errors/project/Q-5-28",
     "since_version": "99.9.9"
+  },
+  "Q-13-8": {
+    "subsystem": "navigation",
+    "title": "Unsupported toc-location value",
+    "message_template": "The `toc-location` option has a value Quarto 2 does not support. Supported values are `left`, `right` (the default), and `body`. The `left-body` and `right-body` double-TOC values are not implemented yet and fall back to `left` / `right`; any other value falls back to the default `right`.",
+    "docs_url": "https://quarto.org/docs/errors/navigation/Q-13-8",
+    "since_version": "99.9.9"
   }
 }
diff --git a/crates/quarto-navigation/src/render_html.rs b/crates/quarto-navigation/src/render_html.rs
index e819e7183..a8173d913 100644
--- a/crates/quarto-navigation/src/render_html.rs
+++ b/crates/quarto-navigation/src/render_html.rs
@@ -251,6 +251,21 @@ pub fn breadcrumbs_to_html(crumbs: &[Crumb], extra_classes: &[&str]) -> String {
 }
 
 pub fn sidebar_to_html(sidebar: &Sidebar, home_url: &str) -> String {
+    sidebar_to_html_with_appended(sidebar, home_url, None)
+}
+
+/// [`sidebar_to_html`] with an extra HTML fragment appended inside the
+/// `nav#quarto-sidebar` element, after the menu.
+///
+/// This is the seam for `toc-location: left` on website pages
+/// (bd-e2kpwy7n): quarto-core's `SidebarRenderTransform` passes the
+/// rendered `nav#TOC` block here so it lands after the nav items —
+/// Q1's `sidebar.ejs` merge order (items first, TOC target last).
+pub fn sidebar_to_html_with_appended(
+    sidebar: &Sidebar,
+    home_url: &str,
+    appended_html: Option<&str>,
+) -> String {
     let mut html = String::new();
 
     let style_class = match sidebar.style {
@@ -291,6 +306,9 @@ pub fn sidebar_to_html(sidebar: &Sidebar, home_url: &str) -> String {
         html.push_str("  </div>\n");
     }
 
+    if let Some(extra) = appended_html {
+        html.push_str(extra);
+    }
     html.push_str("</nav>\n");
     html
 }
diff --git a/docs/errors/navigation/Q-13-8.qmd b/docs/errors/navigation/Q-13-8.qmd
new file mode 100644
index 000000000..b60c24882
--- /dev/null
+++ b/docs/errors/navigation/Q-13-8.qmd
@@ -0,0 +1,55 @@
+---
+title: "Unsupported toc-location value"
+description: "The `toc-location` option has a value Quarto does not support; a fallback placement is used."
+code: Q-13-8
+subsystem: navigation
+status: stub
+since: "99.9.9"
+categories:
+  - navigation
+---
+
+# `Q-13-8` — Unsupported toc-location Value
+
+> The `toc-location` option has a value Quarto does not support;
+> a fallback placement is used.
+
+## What this means
+
+The `toc-location` option controls where the table of contents is
+placed in HTML output:
+
+```yaml
+toc: true
+toc-location: left
+```
+
+Supported values are `left`, `right` (the default), and `body`.
+This warning fires when the option carries any other value. The
+document still renders, with a fallback placement:
+
+- `left-body` falls back to `left`, and `right-body` falls back
+  to `right`. These two values (which in Quarto 1 render a
+  sidebar TOC *plus* a copy in the document body) are not
+  implemented yet.
+- Any other value falls back to the default, `right`.
+
+## Why this happens
+
+Either a typo (`toc-location: lft`), or use of the `left-body` /
+`right-body` double-TOC values, which Quarto 2 does not implement
+yet.
+
+## How to fix
+
+Use one of the supported values:
+
+```yaml
+toc-location: left   # TOC in a left sidebar
+toc-location: right  # TOC in the right margin (default)
+toc-location: body   # TOC at the top of the document body
+```
+
+If you need the `left-body` / `right-body` double-TOC behavior,
+follow Quarto 2 development — until it lands, the sidebar half of
+the value is honored.
diff --git a/docs/guides/authoring/navigation.qmd b/docs/guides/authoring/navigation.qmd
index d7ee979e5..d61ba450d 100644
--- a/docs/guides/authoring/navigation.qmd
+++ b/docs/guides/authoring/navigation.qmd
@@ -2,4 +2,73 @@
 title: Navigation
 ---
 
-TBD.
+## Overview
+
+HTML pages rendered with Quarto can include a table of contents that
+tracks the section structure of the document and lets readers jump to
+any section. This page covers the table of contents options; for
+site-level navigation (navbars, sidebars, breadcrumbs), see the
+[websites guides](../projects/create.qmd).
+
+## Table of Contents
+
+Enable the table of contents with the `toc` option:
+
+``` yaml
+---
+title: My Document
+toc: true
+---
+```
+
+By default the table of contents shows headings up to level 3 and
+renders in the right margin of the page. You can control both:
+
+``` yaml
+---
+title: My Document
+toc: true
+toc-depth: 4
+toc-title: Contents
+---
+```
+
+- `toc-depth` sets the deepest heading level included (default: 3).
+- `toc-title` sets the heading shown above the table of contents
+  (default: "Table of contents", localized to the document language).
+
+## Location
+
+Use `toc-location` to choose where the table of contents appears:
+
+``` yaml
+---
+title: My Document
+toc: true
+toc-location: left
+---
+```
+
+The available locations:
+
+| Value   | Placement                                             |
+|---------|-------------------------------------------------------|
+| `right` | In the right margin (the default)                     |
+| `left`  | In a sidebar to the left of the document body         |
+| `body`  | In the document body, above the content               |
+
+On pages of a website project, `toc-location: left` places the table
+of contents inside the site's navigation sidebar — after the
+navigation entries when the page has a sidebar, or on its own when it
+does not.
+
+On narrow screens the left and right table-of-contents sidebars are
+hidden; use `toc-location: body` if the table of contents should
+remain visible at every screen size.
+
+::: callout-note
+The `left-body` and `right-body` values (which show the table of
+contents both in a sidebar and in the body) are not supported yet;
+they currently fall back to `left` and `right` respectively, with a
+warning.
+:::