docspan 0.4.0__tar.gz → 0.6.0__tar.gz

{docspan-0.4.0 → docspan-0.6.0}/.github/workflows/publish.yml

@@ -3,6 +3,11 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git tag to build and publish (e.g. docspan-v0.4.0)"
+        required: true
 
 jobs:
   build:
@@ -10,19 +15,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          ref: ${{ inputs.ref || github.ref }}
           fetch-depth: 0  # needed for hatch-vcs version from git tags
-
       - name: Install uv
         uses: astral-sh/setup-uv@v4
-
       - name: Build package
         run: uv build
-
       - uses: actions/upload-artifact@v4.6.2
         with:
           name: dist
           path: dist/
-
   publish-testpypi:
     needs: build
     runs-on: ubuntu-latest
@@ -38,11 +40,9 @@ jobs:
         with:
           name: dist
           path: dist/
-
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
-
   publish-pypi:
     needs: publish-testpypi
     runs-on: ubuntu-latest
@@ -58,5 +58,4 @@ jobs:
         with:
           name: dist
           path: dist/
-
       - uses: pypa/gh-action-pypi-publish@release/v1

docspan-0.6.0/.github/workflows/release-please.yml

@@ -0,0 +1,39 @@
+name: Release Please
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write  # to dispatch publish.yml below
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # release-please-action creates the GitHub Release using the default
+      # GITHUB_TOKEN. GitHub doesn't let events produced by that token
+      # trigger other workflows (loop-prevention), so publish.yml's
+      # `on: release: published` trigger never fires for these releases —
+      # dispatch it explicitly instead. workflow_dispatch is exempted from
+      # that restriction even when invoked with GITHUB_TOKEN.
+      - name: Trigger PyPI publish
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run publish.yml \
+            --repo "${{ github.repository }}" \
+            --ref main \
+            -f ref="${{ steps.release.outputs.tag_name }}"

{docspan-0.4.0 → docspan-0.6.0}/.gitignore

@@ -70,3 +70,6 @@ site/
 # repo deliverable (see commits 8f80a5b, bd693ca on other branches)
 .backlog-context.md
 .claude/commands/backlog/
+
+# Scratch artifacts — debug dumps, snapshots, never a repo deliverable
+.scratch/

docspan-0.6.0/.mypy-error-baseline

@@ -0,0 +1 @@
+263

docspan-0.6.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.0"
+}

{docspan-0.4.0 → docspan-0.6.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0](https://github.com/tstapler/docspan/compare/docspan-v0.5.0...docspan-v0.6.0) (2026-09-18)
+
+
+### Features
+
+* **gdocs-sectioned-migrate:** wire migrate-sectioned CLI and pull --to-sectioned (Epic 5) ([4f96b1f](https://github.com/tstapler/docspan/commit/4f96b1f58ab3667b21051fdddb00791a2b1a4086))
+* **google-docs:** add blockquote identity fields to paragraph diff model (Epic 1) ([2b31ddf](https://github.com/tstapler/docspan/commit/2b31ddfcd1d3aa62b170818ca8a5dd95f966df95))
+* **google-docs:** cache rendered mermaid PNGs on disk ([#112](https://github.com/tstapler/docspan/issues/112)) ([8c13a03](https://github.com/tstapler/docspan/commit/8c13a039b309f52833294c034f1aebf16d016f74))
+* **google-docs:** pull native blockquote styling back to markdown (Epic 3) ([20aabc9](https://github.com/tstapler/docspan/commit/20aabc9cd64fbef48180219bbf60334f853d0693))
+* **google-docs:** push blockquotes as native indent/borderLeft styling (Epic 2) ([06881a5](https://github.com/tstapler/docspan/commit/06881a51909cc5bab09d5b61cf58046045262070))
+* **google-docs:** warn and add CI signal for legacy blockquote style upgrades (Epic 4) ([984a2e8](https://github.com/tstapler/docspan/commit/984a2e8bc24e48372e321bbf53008079bcc58c5c))
+
+
+### Bug Fixes
+
+* **cli:** pass full mapping set to cross-doc link resolver on single-file push ([c86dadb](https://github.com/tstapler/docspan/commit/c86dadb532600fd1580e8556a7e0409dac3e44e2))
+* **gdocs-sectioned-migrate:** address verify-review blockers ([0c01490](https://github.com/tstapler/docspan/commit/0c0149075111a56aafb8fd2659582fe2ef6364a0))
+* **google-docs:** comprehensive fix for pull-side image/format lossiness ([#114](https://github.com/tstapler/docspan/issues/114)) ([9dd4834](https://github.com/tstapler/docspan/commit/9dd4834c49cdc5a5a7c427c6a49bce9590898948))
+* **google-docs:** decompose target-side duplicate nodes in replace blocks ([#118](https://github.com/tstapler/docspan/issues/118)) ([e518b14](https://github.com/tstapler/docspan/commit/e518b14d0a820a2a1cb6de25b92deb76d67cd885))
+* **google-docs:** drop unresolvable new images instead of emitting an empty insertInlineImage uri ([#111](https://github.com/tstapler/docspan/issues/111)) ([bc1883d](https://github.com/tstapler/docspan/commit/bc1883dc995b7887f04c08e3d33ab226bf8649cd))
+* **google-docs:** report unreadable bookmark/tab links on tab-scoped pull ([#107](https://github.com/tstapler/docspan/issues/107)) ([be048ca](https://github.com/tstapler/docspan/commit/be048ca00d5e4c40e5d9e617666517d87accb6ae))
+* **google-docs:** tolerate 8-bit RGB quantization in blockquote border detection ([2898434](https://github.com/tstapler/docspan/commit/2898434b5edc2511e552d71ef01ea7393f22ab50))
+
+## [Unreleased]
+
+* **google-docs:** removed the `docspan lint`/style-guide warning against `>` blockquotes now that push emits native blockquote styling instead of literal `>`-prefixed text; if a rendering edge case still misrenders a quote post-push, spot it via `push --dry-run`'s structural diff or by visually inspecting the pushed Doc, since no automated check remains for it.
+
+## [0.5.0](https://github.com/tstapler/docspan/compare/docspan-v0.4.0...docspan-v0.5.0) (2026-08-14)
+
+
+### Features
+
+* **google-docs:** sectioned sync for large document mappings ([#106](https://github.com/tstapler/docspan/issues/106)) ([fe12122](https://github.com/tstapler/docspan/commit/fe121229c8b6b957254020fd2c06241f7506aa80))
+
+
+### Bug Fixes
+
+* **ci:** dispatch PyPI publish from release-please via workflow_dispatch ([e76ffb8](https://github.com/tstapler/docspan/commit/e76ffb8547bfd7d2d2b453a64a5fb3899445fc5f))
+* **confluence:** report internal anchors instead of writing a link to nowhere ([#105](https://github.com/tstapler/docspan/issues/105)) ([cd38f24](https://github.com/tstapler/docspan/commit/cd38f2415e37814e071a180182454d761cfcbfa9))
+* **google-docs:** reset table cell paragraph style to NORMAL_TEXT on fill ([e6db797](https://github.com/tstapler/docspan/commit/e6db797d51746c738586c3cab171367e23bd5be0))
+
 ## [0.4.0](https://github.com/tstapler/docspan/compare/docspan-v0.3.0...docspan-v0.4.0) (2026-08-13)
 
 
@@ -117,6 +158,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **google-docs:** both pull paths now emit the heading's slug. A default (no `tab_id`) pull
   goes through Drive's HTML export, which carries the Doc's opaque `#h.abc123` through
   verbatim; it is upgraded to the slug, so the pulled markdown works as markdown.
+- **google-docs:** a tab-scoped structural pull now renders an ordered-list glyph
+  (`DECIMAL`/`ZERO_DECIMAL`/`ALPHA`/`UPPER_ALPHA`/`ROMAN`/`UPPER_ROMAN`) as `1.`/`2.`/…
+  instead of a plain `-` bullet, numbered per `(listId, nestingLevel)` in document order.
+  One-way: push has no ordered-list concept (every markdown list becomes an unordered
+  bullet regardless of source syntax), so a round-trip through push still loses the
+  numbering — pre-existing, unconditional on both pull paths, not introduced by this fix.
+- **google-docs:** a Markdown `> ...` blockquote now pushes as a native indented,
+  left-bordered paragraph (`indentStart`/`borderLeft`) instead of literal `>` text, and
+  pulling it back reconstructs the `> ` prefix from that styling, byte-for-byte round trip
+  for plain, nested, list-in-quote, and code-fence-in-quote quotes. A Doc still carrying a
+  pre-migration literal-`>` blockquote pulls unchanged and is migrated to the native styling
+  the next time its file is pushed for any reason — a one-time rewrite that, like any other
+  paragraph rewrite, drops comments anchored to it (see the comments-destroyed limitation
+  below).
 
 ### Changed
 - **google-docs:** pass 2 parses and aligns the document once per push instead of three
@@ -128,10 +183,14 @@ Each of these is tracked as a follow-up rather than half-addressed here.
 - An anchor into a heading in a *different tab* of the same document cannot be resolved and
   is reported unresolved. The flat `headingId` member resolves against the tab named in the
   request, so expressing one needs the tabs-aware `Link.heading` member.
-- A pull cannot express a `bookmark`/`bookmarkId` link, a link to a tab, or any link inside
-  a table cell, so those are dropped from the pulled file without a report.
+- A tab-scoped structural pull cannot express a `bookmark`/`bookmarkId` link or a link to a
+  tab (including one inside a table cell — cells route through the same link parsing as
+  everywhere else). These are absent from the pulled file, but reported: `pull` names each
+  unreadable kind in its message rather than dropping them in silence.
 - Confluence writes an internal anchor as a literal `#fragment` href, which it does not
-  resolve.
+  resolve. `push` now reports this as a warning naming the anchor(s) instead of shipping it
+  silently; the href itself is unchanged, since no live instance was available to establish
+  what Confluence actually generates for a heading.
 - An anchor that resolves to nothing is written as plain text, so a later pull replaces the
   author's `[text](#anchor)` with `text`. The push reports it; nothing does afterwards.
 - Such a push exits non-zero on every run, with no flag to suppress it.

{docspan-0.4.0 → docspan-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docspan
-Version: 0.4.0
+Version: 0.6.0
 Summary: Push and pull markdown to Google Docs and Confluence from a single CLI
 Project-URL: Homepage, https://github.com/tstapler/docspan
 Project-URL: Repository, https://github.com/tstapler/docspan
@@ -57,7 +57,7 @@ Description-Content-Type: text/markdown
 
 Push and pull markdown to Google Docs and Confluence from a single CLI. docspan provides bidirectional sync with three-way merge conflict detection, structural diff push that preserves comments on unchanged paragraphs, and a simple YAML-based configuration file.
 
-The config file is named `markgate.yaml` — this name is preserved for backward compatibility and will be renamed in v0.2.0.
+The config file is named `markgate.yaml` for backward compatibility. `docspan.yaml` is also recognized — if present in the working directory (and no `markgate.yaml` is there), docspan reads and writes it instead, so a project can rename its config file at its own pace.
 
 ---
 
@@ -76,6 +76,30 @@ The config file is named `markgate.yaml` — this name is preserved for backward
 pip install docspan
 ```
 
+**Optional: mermaid diagram rendering (Google Docs backend only).** Pushing a
+` ```mermaid ` fence to Google Docs renders it to a PNG via the official
+[mermaid-cli](https://github.com/mermaid-js/mermaid-cli) (`mmdc`), which
+wraps Puppeteer/headless Chrome — there is no pure-Python renderer, so this
+is a Node.js dependency, not a `uv`/`pip` one, and isn't declared in
+`pyproject.toml`. Install it globally so docspan finds a real binary instead
+of falling back to `npx` (which re-fetches on every render):
+
+```bash
+npm install -g @mermaid-js/mermaid-cli   # tested against 11.x; older 10.x should also work
+```
+
+If Puppeteer's headless Chrome cache gets corrupted (a truncated download,
+an interrupted npm install), renders fail with an error like `Could not
+find chrome-headless-shell`; re-fetch it with:
+
+```bash
+npx puppeteer browsers install chrome-headless-shell
+```
+
+Without `mmdc` installed and without network access for `npx` to fetch it
+on demand, a mermaid render failure is reported as a push warning, not a
+crash — see [Limitations](docs/backends/google-docs.md#limitations).
+
 ---
 
 ## Quick start
@@ -203,6 +227,14 @@ docspan status [--config PATH]
 
 Display all configured mappings in a table showing local file, backend, remote ID, and direction.
 
+### `docspan style-guide`
+
+```
+docspan style-guide [--backend google_docs|confluence] [--write FILE]
+```
+
+Print backend authoring guidance (e.g. "one image per line on google_docs"). This ships inside the installed package, so re-running it after a `docspan` upgrade picks up new guidance without hand-copying anything. With `--write FILE`, embed it as a marked, idempotent block in a file in your own repo (a `CLAUDE.md`, a style guide doc, etc.) — re-running updates docspan's managed block in place instead of duplicating it.
+
 ### `docspan auth setup`
 
 ```
@@ -299,6 +331,9 @@ docspan generates these files in your project directory after first sync:
 | `.markgate-base/` | Content-addressed store of merge bases |
 | `{file}.orig` | Backup of local file before merge; deleted after conflict resolution |
 | `{file}.comments.md` | Comment sidecar (Google Docs + Confluence); written during pull if comments exist |
+| `{file}.mermaid-cache.yaml` | Google Docs: maps each pushed `​```mermaid` fence's rendered-PNG hash back to its source, so a *different* machine pulling the doc can still restore the fence instead of a bare image link. Written during push if the file has any mermaid fences. |
+
+**Commit `.markgate-state.json`, `.markgate-base/`, and `{file}.mermaid-cache.yaml` — do not gitignore them.** `.markgate-state.json`/`.markgate-base/` need to be shared for three-way merge to work across machines/teammates; `{file}.mermaid-cache.yaml` is what makes mermaid-fence recovery work across machines at all (Google Docs has no API-writable place to store a diagram's source, only the rendered image — see `mermaid_cache_sidecar.py`'s module docstring for why). `{file}.orig` and `{file}.comments.md` are transient/informational and safe to gitignore if you prefer.
 
 ---
 

{docspan-0.4.0 → docspan-0.6.0}/README.md

@@ -5,7 +5,7 @@
 
 Push and pull markdown to Google Docs and Confluence from a single CLI. docspan provides bidirectional sync with three-way merge conflict detection, structural diff push that preserves comments on unchanged paragraphs, and a simple YAML-based configuration file.
 
-The config file is named `markgate.yaml` — this name is preserved for backward compatibility and will be renamed in v0.2.0.
+The config file is named `markgate.yaml` for backward compatibility. `docspan.yaml` is also recognized — if present in the working directory (and no `markgate.yaml` is there), docspan reads and writes it instead, so a project can rename its config file at its own pace.
 
 ---
 
@@ -24,6 +24,30 @@ The config file is named `markgate.yaml` — this name is preserved for backward
 pip install docspan
 ```
 
+**Optional: mermaid diagram rendering (Google Docs backend only).** Pushing a
+` ```mermaid ` fence to Google Docs renders it to a PNG via the official
+[mermaid-cli](https://github.com/mermaid-js/mermaid-cli) (`mmdc`), which
+wraps Puppeteer/headless Chrome — there is no pure-Python renderer, so this
+is a Node.js dependency, not a `uv`/`pip` one, and isn't declared in
+`pyproject.toml`. Install it globally so docspan finds a real binary instead
+of falling back to `npx` (which re-fetches on every render):
+
+```bash
+npm install -g @mermaid-js/mermaid-cli   # tested against 11.x; older 10.x should also work
+```
+
+If Puppeteer's headless Chrome cache gets corrupted (a truncated download,
+an interrupted npm install), renders fail with an error like `Could not
+find chrome-headless-shell`; re-fetch it with:
+
+```bash
+npx puppeteer browsers install chrome-headless-shell
+```
+
+Without `mmdc` installed and without network access for `npx` to fetch it
+on demand, a mermaid render failure is reported as a push warning, not a
+crash — see [Limitations](docs/backends/google-docs.md#limitations).
+
 ---
 
 ## Quick start
@@ -151,6 +175,14 @@ docspan status [--config PATH]
 
 Display all configured mappings in a table showing local file, backend, remote ID, and direction.
 
+### `docspan style-guide`
+
+```
+docspan style-guide [--backend google_docs|confluence] [--write FILE]
+```
+
+Print backend authoring guidance (e.g. "one image per line on google_docs"). This ships inside the installed package, so re-running it after a `docspan` upgrade picks up new guidance without hand-copying anything. With `--write FILE`, embed it as a marked, idempotent block in a file in your own repo (a `CLAUDE.md`, a style guide doc, etc.) — re-running updates docspan's managed block in place instead of duplicating it.
+
 ### `docspan auth setup`
 
 ```
@@ -247,6 +279,9 @@ docspan generates these files in your project directory after first sync:
 | `.markgate-base/` | Content-addressed store of merge bases |
 | `{file}.orig` | Backup of local file before merge; deleted after conflict resolution |
 | `{file}.comments.md` | Comment sidecar (Google Docs + Confluence); written during pull if comments exist |
+| `{file}.mermaid-cache.yaml` | Google Docs: maps each pushed `​```mermaid` fence's rendered-PNG hash back to its source, so a *different* machine pulling the doc can still restore the fence instead of a bare image link. Written during push if the file has any mermaid fences. |
+
+**Commit `.markgate-state.json`, `.markgate-base/`, and `{file}.mermaid-cache.yaml` — do not gitignore them.** `.markgate-state.json`/`.markgate-base/` need to be shared for three-way merge to work across machines/teammates; `{file}.mermaid-cache.yaml` is what makes mermaid-fence recovery work across machines at all (Google Docs has no API-writable place to store a diagram's source, only the rendered image — see `mermaid_cache_sidecar.py`'s module docstring for why). `{file}.orig` and `{file}.comments.md` are transient/informational and safe to gitignore if you prefer.
 
 ---
 

{docspan-0.4.0 → docspan-0.6.0}/docs/backends/google-docs.md

@@ -56,7 +56,7 @@ mappings:
 !!! warning
     - **Comments destroyed on push for edited paragraphs**: The structural diff preserves comments on unchanged paragraphs, but any paragraph that is deleted and reinserted loses its comments. This is a known v0.1.0 limitation.
     - **Images push and pull**: `![alt](./local.png)` uploads the local file to Drive and references it by URI; an `https://` URL is referenced directly, bypassing upload. Only a standalone image on its own line is supported — one mixed into a paragraph alongside running text is left as plain text. Missing files, files over 50MB, and unsupported formats (SVG) are reported as push warnings rather than blocking the write or crashing.
-    - **Mermaid diagrams push as rendered PNGs**: a fenced ` ```mermaid ` block is rendered to a raster PNG (via `mermaid-cli`/`mmdc`, shelled out to — install with `npm install -g @mermaid-js/mermaid-cli`, or it's fetched on demand through `npx`) and pushed as an inline image, since `insertInlineImage` has no native mermaid or SVG support. A render failure (missing Node.js/mermaid-cli, invalid diagram syntax, timeout) is reported as a push warning, not a crash. There is no pull-side reconstruction — a mermaid diagram round-trips back to markdown as a plain image reference, not a ` ```mermaid ` fence.
+    - **Mermaid diagrams push as rendered PNGs**: a fenced ` ```mermaid ` block is rendered to a raster PNG (via the official `mermaid-cli`/`mmdc`, shelled out to — install with `npm install -g @mermaid-js/mermaid-cli`, tested against 11.x, or it's fetched on demand through `npx`, which re-downloads on every render) and pushed as an inline image, since `insertInlineImage` has no native mermaid or SVG support. See [Install](../../README.md#install) for setup, including the fix for a corrupted Puppeteer headless-Chrome cache. A render failure (missing Node.js/mermaid-cli, invalid diagram syntax, timeout) is reported as a push warning, not a crash. Successful renders are cached on disk (keyed on diagram text, render scale, and the resolved `mmdc --version`) under `$XDG_CACHE_HOME/docspan/mermaid`, so an unchanged fence across repeat pushes skips the mermaid-cli/Puppeteer invocation entirely. There is no pull-side reconstruction — a mermaid diagram round-trips back to markdown as a plain image reference, not a ` ```mermaid ` fence.
     - **Pulled image URIs can go stale**: a pulled `![alt](src)` link is Google's `contentUri` for that embedded object, which Google's API docs say may change over time even when the image itself is unchanged. The push structural diff keys image identity on `alt`/width/height, not this URI, so a rotated `contentUri` alone will not cause the paragraph to be deleted and reinserted (which would destroy any comment anchored to it) — but the stale URI persisted in your markdown file can still surface as a one-sided edit in `docspan conflicts resolve`'s three-way diff.
     - **Table cells hold one paragraph**: a markdown table cell is pushed as a single
       paragraph, and inline formatting inside it (bold, monospace, links, internal
@@ -65,3 +65,6 @@ mappings:
       table created by the current push gets its cell styling on the *next* push —
       docspan reports both rather than failing silently.
     - **Rate limiting**: The Google Docs API allows 300 requests per minute per project. Large documents with many changed paragraphs may trigger rate limit errors.
+    - **Blockquotes render as an indented, left-bordered callout**: a Markdown `> ...` line is pushed as a paragraph with native `indentStart`/`borderLeft` styling (no literal `>` text), and pulling that paragraph back reconstructs the `> ` prefix from that styling, byte-for-byte, independent of the visual border. A Doc that still has a *pre-migration* blockquote (pushed by an older docspan version as literal `>` text) keeps rendering as plain text until the file containing it is pushed again for any reason — at that point every legacy blockquote in the file is deleted and reinserted with native styling in that same push, which, per the comments limitation above, destroys any comment anchored to one of those paragraphs. This is a one-time cost per file, not a recurring one. Very large files with many legacy blockquotes could in principle hit the Google Docs API's `batchUpdate` payload-size cap during that one migrating push; this has not been reproduced or quantified against a real document.
+
+        Both `docspan push --dry-run` and a real `docspan push` print a `STYLE_UPGRADE_COUNT=<N>` line for each run, counting the legacy blockquote paragraphs about to be (or that were) rewritten to native styling — `0` when there are none. This is a plain, machine-parsable line meant for CI: grep it out of the output rather than parsing the human-readable `⚠` warnings above it. Pass `--fail-on-comment-loss` to make `push` exit non-zero when `STYLE_UPGRADE_COUNT` is greater than zero; without the flag the count is reporting-only and never affects the exit code or blocks the write.

{docspan-0.4.0 → docspan-0.6.0}/docs/install.md

@@ -16,12 +16,14 @@ pip install docspan
 uv add docspan
 ```
 
-## Install via pipx
+## Install via uv tool / uvx
 
 ```bash
-pipx install docspan
+uv tool install docspan
 ```
 
+To run it without installing, use `uvx docspan`.
+
 ---
 
 ## Google Docs Auth Setup

docspan-0.6.0/project_plans/gdocs-native-blockquotes/decisions/ADR-001-native-blockquote-indent-and-border-styling.md

@@ -0,0 +1,38 @@
+# ADR-001: Blockquotes render as native indent + `borderLeft`, using a docspan-owned marker, migrated lazily
+
+## Status
+Accepted
+
+## Context
+
+`markdown_to_paragraph_parser.py`'s `_walk_block_quote` currently renders a markdown `>` blockquote by prefixing each produced paragraph's text with literal `"> "` characters (`_prefix_node_text`). Google Docs has no built-in blockquote paragraph style, so the literal `> ` text is the only signal a reader sees — it renders as plain, unstyled text starting with a greater-than sign, which users report as looking broken rather than as an intentional callout (`requirements.md`'s Problem Statement).
+
+Three approaches were considered (`implementation/plan.md`'s Step 0.5 creative pass):
+
+1. **Tighten lint/style-guide wording only** — tells authors not to use `>`, doesn't fix the rendering.
+2. **Strip `>` and italicize** — simple, but loses the "set apart as an aside" visual signal the job-to-be-done research (`research/ux.md` §5) confirms is the actual reason authors reach for `>`.
+3. **Native `indentStart` + `borderLeft` styling, chosen here** — matches the convention independently observed across Pandoc→docx (`Block Text` style, indent-led), Notion (indent + left border, no fill), and Confluence Cloud's newer blockquote block (`research/ux.md` §1), and is corroborated as the de facto community detection heuristic by `gd2md-html` (`research/build-vs-buy.md` §4).
+
+Google's Docs API v1 exposes `ParagraphStyle.indentStart` (a `Dimension`) and `ParagraphStyle.borderLeft` (a `ParagraphBorder`: color, width, dashStyle, padding) as the primitives. There is no first-class "blockquote" style; docspan must define and own a marker combination on both fields to safely round-trip identity through them.
+
+## Decision
+
+- A blockquote paragraph is represented by two new `DocsParagraphNode` fields, `is_blockquote: bool` and `quote_depth: int`, decoupled entirely from `node.text` (no more literal `"> "` embedded in the text).
+- On push, `is_blockquote`/`quote_depth` translate to `indentStart` (scaled by `quote_depth` × a fixed points-per-level constant) and a full `borderLeft` `ParagraphBorder` object using a distinctive, docspan-owned color/width/dashStyle combination (`BLOCKQUOTE_BORDER_MARKER`, values fixed by a live-Doc spike, Epic 0 in `implementation/plan.md`) — computed by one shared helper (`_blockquote_paragraph_style_fields`) called from both the insert-path and restyle-path `updateParagraphStyle` request sites in `docs_request_builder.py`, so the two paths cannot drift.
+- On pull, `docs_structure_parser.py`'s `_parse_paragraph` recognizes that exact marker/indent combination and sets `is_blockquote`/`quote_depth` accordingly; `nodes_to_markdown.py` reconstructs `"> " * quote_depth` markdown prefixes at render time via a new `_group_blockquote_runs` grouping stage (composed as the outer stage around the existing `_group_code_runs`) and a new `BlockquoteNodeRenderer`.
+- `is_blockquote`/`quote_depth` participate in `_node_key` (diff-alignment identity) but are excluded from `_content_key` (restyle-vs-rewrite classification), mirroring the existing `render_prefix`/image-`src` precedent — so a pure blockquote-styling change can still be expressed as an in-place restyle rather than a destructive delete+reinsert wherever possible.
+- **Migration is lazy and unconditional — no feature flag.** A previously-pushed literal-`> `-text paragraph is left exactly as-is until the next time that specific paragraph is pushed with a change; at that point it is deleted and reinserted (since removing the embedded `"> "` from `node.text` is itself a text change), and any comment anchored to it is lost — the same cost as any other delete+reinsert today. This is a deliberate, accepted, one-time-per-paragraph cost, not an oversight; `push --dry-run` calls it out via a new `style_upgrade` reason on `HighRiskParagraph` (`implementation/plan.md` Epic 4) so it's distinguishable from unrelated diff-engine churn.
+- **List-in-quote indent stacking is additive by construction, not by explicit combined-indent code.** `docs_request_builder.py`'s existing list handling derives bullet indentation from `CreateParagraphBulletsRequest`, keyed on leading-tab count in the paragraph's text — not from any `paragraphStyle.indentStart` docspan sets. The blockquote's `indentStart` (from `quote_depth`) is a wholly separate paragraph-style field. Because the two indent sources are independent fields consumed by independent Docs mechanisms, a paragraph that is both a list item and a blockquote gets both indents simultaneously with no interaction code required — confirmed against a live Doc in Epic 0's spike (`implementation/plan.md` Story 2.6), not assumed from reading the code alone.
+- `borderLeft` was independently confirmed (not merely assumed) to render unconditionally per paragraph — Google Docs' visual border-coalescing behavior applies to `borderTop`/`borderBottom`/`borderBetween` sub-fields, not `borderLeft` — so no live-Doc spike is required to settle the coalescing question specifically; it is resolved by this ADR, not deferred.
+- `lint.py`'s `find_blockquote_issues` and the corresponding `GOOGLE_DOCS_STYLE_GUIDE` bullet warning against `>` are **deleted outright**, not narrowed. The lint rule's own module docstring already scopes it specifically to google_docs (Confluence already renders blockquotes natively); once google_docs also does, there is no backend left for the rule to protect against, and a narrowed "for future backends" version would be speculative, untested YAGNI.
+- `is_blockquote`/`quote_depth` are an intentionally-paired invariant, not two independent fields: `is_blockquote == (quote_depth > 0)` is enforced in `DocsParagraphNode.__post_init__` (raising `ValueError` otherwise), rather than collapsed into a single derived field. A single field was considered and rejected here specifically because it would ripple a field-shape change through every story in `implementation/plan.md` that constructs both fields together; a construction-time invariant closes the same illegal-state gap at a fraction of the cost.
+- Marker detection on pull compares only the `color`/`width`/`dashStyle` sub-fields docspan itself writes into `borderLeft`, not whole-dict equality against `BLOCKQUOTE_BORDER_MARKER`. This is deliberate: Google's Docs API may echo back additional normalized sub-fields (e.g. a default `padding` or `unit`) that were never sent, and blanket `==` would then falsely report "not a blockquote" for docspan's own paragraphs.
+- `BLOCKQUOTE_BORDER_MARKER`/`BLOCKQUOTE_INDENT_PT_PER_LEVEL` are owned by `docs_structure_parser.py` (the pull-side module) and imported — never redefined or copied — by `docs_request_builder.py` (the push-side module), so there is exactly one source of truth for the marker's identity, consistent with `_blockquote_paragraph_style_fields` avoiding the same class of drift within the push side alone.
+
+## Consequences
+
+- **Comment-loss risk is accepted, not eliminated**, for every already-pushed blockquote in every mapped document, on its first post-migration push. This is the direct tradeoff for fixing rendering without a migration tool or feature flag; `implementation/plan.md`'s Migration Plan and Epic 4 exist specifically to make this visible in `--dry-run`, not to prevent it.
+- **False-positive marker detection remains probabilistic, not exact.** A human-applied Docs UI border that happens to coincidentally match `BLOCKQUOTE_BORDER_MARKER`'s exact color/width/dashStyle would be misdetected as a docspan blockquote on pull. This is accepted as an explicit non-goal of perfect detection (mitigated only by choosing a visually distinctive marker in Epic 0), consistent with the same class of magic-constant risk the codebase already accepts elsewhere (`render_prefix`), and is documented here so a future bug report isn't read as a design failure.
+- **Marker migration risk**: if `BLOCKQUOTE_BORDER_MARKER`'s value is ever changed in a future release, documents pushed under the old marker silently stop being recognized as blockquotes on pull. Unlike the render-glyph fix (`31b4edd`, which uses a Unicode category rather than a hardcoded codepoint specifically to avoid this class of problem), there is no equivalent "any value of this shape" fallback available for an arbitrary border/indent combination, since arbitrary colors/widths are also legitimate for non-docspan content. If the marker must ever change, a follow-up migration path will be needed; none is designed here. Forward-looking note for future maintainers: if the Docs API ever exposes a first-class custom-paragraph-style-id (as opposed to raw style-field values), that would let a future release stop relying on a probabilistic border/indent match entirely — worth checking for before inventing a bespoke migration scheme.
+- **Documented non-goal**: this feature delivers indent+border "this is set apart" signaling only. It explicitly does not implement GitHub-style `[!NOTE]`/`[!WARNING]` admonition syntax, background tint, or icons (the heavier "callout" affordance Notion/Confluence separately offer) — confirmed by `research/ux.md` §5 as a materially bigger, distinct feature, not a corner cut in this one. A future feature request for colored callout boxes is new scope, not evidence this project under-delivered.
+- Two empirical unknowns are *not* resolved by this ADR and remain open, gated on a live-Doc spike (`implementation/plan.md` Epic 0, Unresolved Questions 1-3): the exact marker color/width/dashStyle values, whether omitting a `ParagraphBorder` sub-field on write leaves it unset vs. resets it to a Docs-side default, and whether a table cell inherits an adjacent blockquote's `indentStart`/`borderLeft` the way it's confirmed to inherit `namedStyleType` (`e6db797` precedent).