docspan 0.1.0__tar.gz → 0.2.0__tar.gz

{docspan-0.1.0 → docspan-0.2.0}/.github/workflows/publish.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Build package
         run: uv build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v4.6.2
         with:
           name: dist
           path: dist/
@@ -31,8 +31,10 @@ jobs:
       url: https://test.pypi.org/p/docspan
     permissions:
       id-token: write
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v4.3.0
         with:
           name: dist
           path: dist/
@@ -49,8 +51,10 @@ jobs:
       url: https://pypi.org/p/docspan
     permissions:
       id-token: write
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v4.3.0
         with:
           name: dist
           path: dist/

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

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

docspan-0.2.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+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.2.0](https://github.com/tstapler/docspan/compare/docspan-v0.1.0...docspan-v0.2.0) (2026-07-22)
+
+
+### Features
+
+* Add Railway Volume support for persistent state storage ([3a4b76e](https://github.com/tstapler/docspan/commit/3a4b76eb0cbc14afa02f3aa3de2c4607808fad9f))
+* Add retry mechanism and improved error handling for Google Drive API ([e8a7b5f](https://github.com/tstapler/docspan/commit/e8a7b5f177ad2c3b8a356852eceb827326f8ce76))
+* Auto-reload Google Sheet mappings on each sync cycle ([a2647c6](https://github.com/tstapler/docspan/commit/a2647c6c1435eb5624a389a4e673a57ead012123))
+* **config:** XDG storage paths + central config with project prefixes ([#7](https://github.com/tstapler/docspan/issues/7)) ([0aa9165](https://github.com/tstapler/docspan/commit/0aa9165d24df95386b514d283cf846a2cdc809f7))
+* **confluence:** port adf/markdown/services from markdown-confluence ([e9d1a85](https://github.com/tstapler/docspan/commit/e9d1a85a9747ac75a6d95d6351d18483297726a4))
+* **google_docs:** checklist round-trip + comment/glyph-risk push gate ([#8](https://github.com/tstapler/docspan/issues/8)) ([bd2a885](https://github.com/tstapler/docspan/commit/bd2a885d6a2e18b758f12fc4a2aaf588c045d059))
+* **google_docs:** docspan comments respond — reply/resolve round-trip ([#13](https://github.com/tstapler/docspan/issues/13)) ([7a662ed](https://github.com/tstapler/docspan/commit/7a662edb14b6f0078fcca110023cfc7e54724726))
+* **google-docs:** add per-user OAuth auth option ([#4](https://github.com/tstapler/docspan/issues/4)) ([830369c](https://github.com/tstapler/docspan/commit/830369cba1817224ae0d02f0b14b6a84de84a4eb))
+* **google-docs:** push markdown tables and inline links/formatting ([#3](https://github.com/tstapler/docspan/issues/3)) ([5b74246](https://github.com/tstapler/docspan/commit/5b74246eb1070355b39c5e84292e59f443457875))
+* **google-docs:** read comments into a {file}.comments.md sidecar on pull ([#5](https://github.com/tstapler/docspan/issues/5)) ([aca2264](https://github.com/tstapler/docspan/commit/aca226412ef74c80603678d7ae1defaa25e38954))
+* scaffold markgate package from google-docs-obsidian-sync fork ([44dd3c5](https://github.com/tstapler/docspan/commit/44dd3c586a670b4689154b2db9bc6cb8673d9702))
+* **sync:** Google Docs structural-diff push, Confluence comments, three-way merge ([9a20e34](https://github.com/tstapler/docspan/commit/9a20e3452f2d92a240128d7c8e2f9c4b63a547f9))
+
+
+### Bug Fixes
+
+* **ci:** add __future__ annotations for Python 3.9 compat in test ([9ceca65](https://github.com/tstapler/docspan/commit/9ceca65ca5ad2040c1c2ec215fc097b02ba1a0c4))
+* **ci:** apply ruff autofix across all src and test files ([bee2784](https://github.com/tstapler/docspan/commit/bee2784b940d872045ce33faf0ce53f65150d80d))
+* **ci:** resolve ruff lint failures and enable Actions PR creation ([8727e7b](https://github.com/tstapler/docspan/commit/8727e7bcabf1ddec4b4116b06e605ff24d0eaffe))
+* **google-docs:** don't drop blockquote paragraphs on push ([#9](https://github.com/tstapler/docspan/issues/9)) ([e3b2597](https://github.com/tstapler/docspan/commit/e3b259799acfcdaa7f884edb49633f349860a978))
+* **google-docs:** fix inline-style paragraph misalignment on push ([#10](https://github.com/tstapler/docspan/issues/10)) ([4f79ef8](https://github.com/tstapler/docspan/commit/4f79ef8b4669eee4d6fe361af5bae68bb4486019))
+* **google-docs:** fix mid-document insert off-by-one causing paragraph merges ([#12](https://github.com/tstapler/docspan/issues/12)) ([c74bea2](https://github.com/tstapler/docspan/commit/c74bea2d6464df0c19abce31a39aea0bc18d1e46))
+* **google-docs:** restore inline styling and unwrap redirect links on pull ([#11](https://github.com/tstapler/docspan/issues/11)) ([b90466c](https://github.com/tstapler/docspan/commit/b90466cd9765a290b02634bbe9b3869185e308bc))
+* Improve nested list indentation in Google Docs to Markdown conversion ([d6a7539](https://github.com/tstapler/docspan/commit/d6a7539d4beade3426e5d0db838f1d9974f7294b))
+* Remove CONFIG_YAML dependency, prefer individual env vars ([d5d5d4a](https://github.com/tstapler/docspan/commit/d5d5d4ae25a7c1d7a213071f968eba56a9289da3))
+* Resolve service account storage quota error by storing sync state locally ([00e9cb6](https://github.com/tstapler/docspan/commit/00e9cb65033dfb6cca8e0aae2258cde458cfb342))
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-07
+
+### Added
+- `docspan push` — push local markdown files to Google Docs or Confluence
+- `docspan pull` — pull remote documents into local markdown files with three-way merge
+- `docspan status` — show current mapping status in a table
+- `docspan auth setup` — interactive authentication setup for `google_docs` and `confluence` backends
+- `docspan conflicts list` — list files with unresolved merge conflicts
+- `docspan conflicts resolve` — resolve merge conflicts with `remote`, `local`, or `merged` strategy
+- Google Docs backend: push and pull via Google Docs API (service account auth)
+- Confluence backend: push and pull via Atlassian REST API (API token auth)
+- Three-way merge for bidirectional sync conflict detection
+- Confluence comment sidecar: pull writes inline and footer comments to `{file}.comments.md`
+- `markgate.yaml` config file format with per-mapping direction control (`push`/`pull`/`both`)
+- Sync state tracking via `.markgate-state.json` and content-addressed base store in `.markgate-base/`
+
+### Known Limitations
+- Google Docs: comments on edited paragraphs are destroyed on push (paragraph-level diff; comments on unchanged paragraphs are preserved)
+- Push: no image support — local image files cannot be pushed to Google Docs or Confluence
+- Push: no table support — markdown tables are not rendered in Google Docs
+- Confluence: requires an Atlassian API token; no OAuth flow
+- Confluence: comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back
+- Config file is named `markgate.yaml` (not `docspan.yaml`) and state file is `.markgate-state.json` (not `.docspan-state.json`). These will be renamed in v0.2.0.
+
+[Unreleased]: https://github.com/tstapler/docspan/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tstapler/docspan/releases/tag/v0.1.0

{docspan-0.1.0 → docspan-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: docspan
-Version: 0.1.0
+Version: 0.2.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
@@ -142,6 +142,38 @@ mappings:
 
 ---
 
+## Central config & XDG storage
+
+By default docspan stores its config, sync state, and credentials under the [XDG base directories](https://specifications.freedesktop.org/basedir-spec/latest/), and a **central config** lets you register multiple projects by *prefix* and run docspan from anywhere.
+
+```
+$XDG_CONFIG_HOME/docspan/config.yaml     # central config (project registry)
+$XDG_CONFIG_HOME/docspan/<prefix>/…      # cached OAuth token
+$XDG_STATE_HOME/docspan/<prefix>/…       # sync state + base store, per project
+```
+
+Central config (`~/.config/docspan/config.yaml`):
+
+```yaml
+default_prefix: design-docs
+projects:
+  design-docs:
+    markgate: ~/Documents/design-docs/markgate.yaml
+```
+
+Register and use projects:
+
+```bash
+docspan config add design-docs ~/Documents/design-docs/markgate.yaml   # register (prefix → markgate.yaml)
+docspan config show                                                    # list projects + active resolution
+docspan push --prefix design-docs                                      # or DOCSPAN_PREFIX, or default_prefix, or cwd match
+docspan migrate-xdg --prefix design-docs                               # move legacy in-repo state to XDG + register
+```
+
+**Prefix resolution order:** `--config PATH` (legacy — storage stays beside the file) → `--prefix` → `DOCSPAN_PREFIX` → cwd inside a registered project → `default_prefix`. If nothing matches, docspan falls back to a local `./markgate.yaml` with beside-the-file storage (fully backward-compatible).
+
+---
+
 ## Command Reference
 
 ### `docspan push`
@@ -158,7 +190,7 @@ Push local markdown files to remote docs. Skips mappings with `direction = "pull
 docspan pull [FILES]... [--dry-run] [--config PATH]
 ```
 
-Pull remote documents into local markdown files with three-way merge. Writes conflict markers to the file if automatic merge fails.
+Pull remote documents into local markdown files with three-way merge. Writes conflict markers to the file if automatic merge fails. For Google Docs, also writes a `{file}.comments.md` sidecar of the doc's comments (open + resolved, with quoted selections and reply threads) unless `pull_comments: false`.
 
 ### `docspan status`
 
@@ -176,7 +208,17 @@ docspan auth setup BACKEND [--config PATH]
 
 Interactive authentication setup. `BACKEND` is one of `google_docs` or `confluence`.
 
-For Google Docs, prints step-by-step service account setup instructions. For Confluence, prompts for base URL, username, and API token, then prints a YAML snippet to add to `markgate.yaml`.
+For **Google Docs**, run it with no flags for a guided flow:
+
+```
+docspan auth setup google_docs
+```
+
+It detects your current state, lets you pick **Personal (OAuth)** [recommended] or **Service account**, auto-detects a `client_secret.json` (scanning `.`, `.markgate/`, `~/Downloads`) or prompts for the path with validation, runs the browser sign-in, verifies the connection, and offers to persist the choice into `markgate.yaml` so you never repeat it. In a non-TTY/CI environment it prints manual instructions instead of prompting.
+
+Everything is scriptable — any answer can be supplied as a flag: `--oauth` / `--service-account`, `--client-secret PATH`, `--credentials PATH`. If a `docspan push`/`pull` runs without credentials in an interactive terminal, it offers to run setup inline and then continues.
+
+For **Confluence**, prompts for base URL, username, and API token, then prints a YAML snippet to add to `markgate.yaml`.
 
 ### `docspan conflicts list`
 
@@ -208,10 +250,14 @@ Resolve a merge conflict in a tracked file.
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `credentials_path` | string | null | Path to Google service account JSON key |
-| `token_path` | string | `.markgate/google_token.json` | OAuth token storage path |
+| `credentials_path` | string | null | Path to a Google **service account** JSON key |
+| `oauth_client_secret_path` | string | null | Path to an **OAuth client secret** JSON (Desktop app) for per-user auth |
+| `token_path` | string | `$XDG_CONFIG_HOME/docspan/google_token.json` | Where the cached OAuth user token is stored/refreshed (out of the repo) |
+| `pull_comments` | bool | `true` | On pull, write a `{file}.comments.md` sidecar of the doc's comments |
 
-**Environment variable alternatives:**
+Auth resolution order: `credentials_path` → `ACCOUNT_A_CREDENTIALS[_PATH]` env → per-user OAuth (`oauth_client_secret_path`, or an already-cached `token_path`).
+
+**Environment variable alternatives (service account):**
 - `ACCOUNT_A_CREDENTIALS_PATH` — path to service account JSON
 - `ACCOUNT_A_CREDENTIALS` — inline service account JSON string
 
@@ -248,7 +294,7 @@ docspan generates these files in your project directory after first sync:
 | `.markgate-state.json` | Sync state tracking (content hashes, remote versions) |
 | `.markgate-base/` | Content-addressed store of merge bases |
 | `{file}.orig` | Backup of local file before merge; deleted after conflict resolution |
-| `{file}.comments.md` | Confluence comment sidecar; written during pull if comments exist |
+| `{file}.comments.md` | Comment sidecar (Google Docs + Confluence); written during pull if comments exist |
 
 ---
 
@@ -257,11 +303,15 @@ docspan generates these files in your project directory after first sync:
 > [!NOTE]
 > **Known limitations in v0.1.0**
 >
-> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved)
+> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved). `docspan push --dry-run` and a default fail-closed `--force`-gated block now warn before this happens — it is still not prevented.
 > - Push: no image support — local images cannot be pushed to Google Docs or Confluence
 > - Push: no table support — markdown tables are not rendered in Google Docs
 > - Confluence: requires an Atlassian API token; no OAuth flow
 > - Confluence: the comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back
+> - Checklist state (`- [ ]`/`- [x]`) round-trips as literal text — Google Docs' native checkbox glyph is intentionally not used because its checked/unchecked state cannot be read back via the API (see ADR-001)
+> - `push --dry-run` now shows a real structural diff and flags paragraphs with open comments at risk; `push` blocks by default on a flagged paragraph unless `--force` is passed
+> - If a push succeeds but a post-push check finds the open-comment count dropped, docspan reports this as a `⚠` warning — never a plain green success — so it's never mistaken for a clean push
+> - Google Docs OAuth requires each user to create their own GCP project (`docspan auth setup google_docs` → Personal/OAuth) and stays in Google's "Testing" publishing status — capped at 100 test users, with Google's "app isn't verified" warning shown on first sign-in. This avoids the annual CASA security assessment required to verify apps requesting Drive/Docs' restricted read-write scopes (a real recurring cost), at the price of a few extra manual setup minutes per user instead of a single embedded, zero-config client. Revisit if/when adoption outgrows a per-user-project model — options are paying for verification, or narrowing to the unrestricted `drive.file` scope via Google's Picker API (bigger rework: requires the user to explicitly select their doc through a picker rather than referencing it by ID in config)
 
 ---
 

{docspan-0.1.0 → docspan-0.2.0}/README.md

@@ -93,6 +93,38 @@ mappings:
 
 ---
 
+## Central config & XDG storage
+
+By default docspan stores its config, sync state, and credentials under the [XDG base directories](https://specifications.freedesktop.org/basedir-spec/latest/), and a **central config** lets you register multiple projects by *prefix* and run docspan from anywhere.
+
+```
+$XDG_CONFIG_HOME/docspan/config.yaml     # central config (project registry)
+$XDG_CONFIG_HOME/docspan/<prefix>/…      # cached OAuth token
+$XDG_STATE_HOME/docspan/<prefix>/…       # sync state + base store, per project
+```
+
+Central config (`~/.config/docspan/config.yaml`):
+
+```yaml
+default_prefix: design-docs
+projects:
+  design-docs:
+    markgate: ~/Documents/design-docs/markgate.yaml
+```
+
+Register and use projects:
+
+```bash
+docspan config add design-docs ~/Documents/design-docs/markgate.yaml   # register (prefix → markgate.yaml)
+docspan config show                                                    # list projects + active resolution
+docspan push --prefix design-docs                                      # or DOCSPAN_PREFIX, or default_prefix, or cwd match
+docspan migrate-xdg --prefix design-docs                               # move legacy in-repo state to XDG + register
+```
+
+**Prefix resolution order:** `--config PATH` (legacy — storage stays beside the file) → `--prefix` → `DOCSPAN_PREFIX` → cwd inside a registered project → `default_prefix`. If nothing matches, docspan falls back to a local `./markgate.yaml` with beside-the-file storage (fully backward-compatible).
+
+---
+
 ## Command Reference
 
 ### `docspan push`
@@ -109,7 +141,7 @@ Push local markdown files to remote docs. Skips mappings with `direction = "pull
 docspan pull [FILES]... [--dry-run] [--config PATH]
 ```
 
-Pull remote documents into local markdown files with three-way merge. Writes conflict markers to the file if automatic merge fails.
+Pull remote documents into local markdown files with three-way merge. Writes conflict markers to the file if automatic merge fails. For Google Docs, also writes a `{file}.comments.md` sidecar of the doc's comments (open + resolved, with quoted selections and reply threads) unless `pull_comments: false`.
 
 ### `docspan status`
 
@@ -127,7 +159,17 @@ docspan auth setup BACKEND [--config PATH]
 
 Interactive authentication setup. `BACKEND` is one of `google_docs` or `confluence`.
 
-For Google Docs, prints step-by-step service account setup instructions. For Confluence, prompts for base URL, username, and API token, then prints a YAML snippet to add to `markgate.yaml`.
+For **Google Docs**, run it with no flags for a guided flow:
+
+```
+docspan auth setup google_docs
+```
+
+It detects your current state, lets you pick **Personal (OAuth)** [recommended] or **Service account**, auto-detects a `client_secret.json` (scanning `.`, `.markgate/`, `~/Downloads`) or prompts for the path with validation, runs the browser sign-in, verifies the connection, and offers to persist the choice into `markgate.yaml` so you never repeat it. In a non-TTY/CI environment it prints manual instructions instead of prompting.
+
+Everything is scriptable — any answer can be supplied as a flag: `--oauth` / `--service-account`, `--client-secret PATH`, `--credentials PATH`. If a `docspan push`/`pull` runs without credentials in an interactive terminal, it offers to run setup inline and then continues.
+
+For **Confluence**, prompts for base URL, username, and API token, then prints a YAML snippet to add to `markgate.yaml`.
 
 ### `docspan conflicts list`
 
@@ -159,10 +201,14 @@ Resolve a merge conflict in a tracked file.
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `credentials_path` | string | null | Path to Google service account JSON key |
-| `token_path` | string | `.markgate/google_token.json` | OAuth token storage path |
+| `credentials_path` | string | null | Path to a Google **service account** JSON key |
+| `oauth_client_secret_path` | string | null | Path to an **OAuth client secret** JSON (Desktop app) for per-user auth |
+| `token_path` | string | `$XDG_CONFIG_HOME/docspan/google_token.json` | Where the cached OAuth user token is stored/refreshed (out of the repo) |
+| `pull_comments` | bool | `true` | On pull, write a `{file}.comments.md` sidecar of the doc's comments |
 
-**Environment variable alternatives:**
+Auth resolution order: `credentials_path` → `ACCOUNT_A_CREDENTIALS[_PATH]` env → per-user OAuth (`oauth_client_secret_path`, or an already-cached `token_path`).
+
+**Environment variable alternatives (service account):**
 - `ACCOUNT_A_CREDENTIALS_PATH` — path to service account JSON
 - `ACCOUNT_A_CREDENTIALS` — inline service account JSON string
 
@@ -199,7 +245,7 @@ docspan generates these files in your project directory after first sync:
 | `.markgate-state.json` | Sync state tracking (content hashes, remote versions) |
 | `.markgate-base/` | Content-addressed store of merge bases |
 | `{file}.orig` | Backup of local file before merge; deleted after conflict resolution |
-| `{file}.comments.md` | Confluence comment sidecar; written during pull if comments exist |
+| `{file}.comments.md` | Comment sidecar (Google Docs + Confluence); written during pull if comments exist |
 
 ---
 
@@ -208,11 +254,15 @@ docspan generates these files in your project directory after first sync:
 > [!NOTE]
 > **Known limitations in v0.1.0**
 >
-> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved)
+> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved). `docspan push --dry-run` and a default fail-closed `--force`-gated block now warn before this happens — it is still not prevented.
 > - Push: no image support — local images cannot be pushed to Google Docs or Confluence
 > - Push: no table support — markdown tables are not rendered in Google Docs
 > - Confluence: requires an Atlassian API token; no OAuth flow
 > - Confluence: the comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back
+> - Checklist state (`- [ ]`/`- [x]`) round-trips as literal text — Google Docs' native checkbox glyph is intentionally not used because its checked/unchecked state cannot be read back via the API (see ADR-001)
+> - `push --dry-run` now shows a real structural diff and flags paragraphs with open comments at risk; `push` blocks by default on a flagged paragraph unless `--force` is passed
+> - If a push succeeds but a post-push check finds the open-comment count dropped, docspan reports this as a `⚠` warning — never a plain green success — so it's never mistaken for a clean push
+> - Google Docs OAuth requires each user to create their own GCP project (`docspan auth setup google_docs` → Personal/OAuth) and stays in Google's "Testing" publishing status — capped at 100 test users, with Google's "app isn't verified" warning shown on first sign-in. This avoids the annual CASA security assessment required to verify apps requesting Drive/Docs' restricted read-write scopes (a real recurring cost), at the price of a few extra manual setup minutes per user instead of a single embedded, zero-config client. Revisit if/when adoption outgrows a per-user-project model — options are paying for verification, or narrowing to the unrestricted `drive.file` scope via Google's Picker API (bigger rework: requires the user to explicitly select their doc through a picker rather than referencing it by ID in config)
 
 ---
 

{docspan-0.1.0 → docspan-0.2.0}/markgate.yaml.example

@@ -5,8 +5,13 @@
 
 backends:
   google_docs:
+    # Service-account auth (app / non-user):
     credentials_path: /path/to/service-account.json
     # or set ACCOUNT_A_CREDENTIALS_PATH env var
+    #
+    # Or per-user OAuth (acts as you, like gws — no service account):
+    # oauth_client_secret_path: /path/to/client_secret.json
+    # token_path: .markgate/google_token.json   # cached user token (default)
 
   confluence:
     base_url: https://yourorg.atlassian.net

docspan-0.2.0/project_plans/bidirectional-comments/plan.md

@@ -0,0 +1,212 @@
+# SDD Plan: Bidirectional Google Docs Comments
+
+**Status:** planning only (no code) · **Backend:** `google_docs` · **Related:** read-only comments reader (PR #5)
+
+> Storage locations below (base snapshot, state) are shown at their current repo-relative paths. If the
+> XDG-paths + central-config refactor lands first, these move under the XDG data/state root — the design
+> is unchanged, only the root differs.
+
+---
+
+## 1. Requirements
+
+### Functional
+- **FR1 — Pull others' comments** (exists in PR #5, being refactored): fetch all threads (open + resolved) with replies, quoted selection, author, timestamps; materialize locally.
+- **FR2 — Reply to existing threads:** user writes a reply into a local thread file; `push` creates it via `replies.create` on the parent comment.
+- **FR3 — Add new comments:** `push` creates via `comments.create`. On Google Docs these land **unanchored** (ADR-004).
+- **FR4 — Resolve / reopen:** `push` applies via `replies.create` with `action=resolve|reopen`.
+- **FR5 — Round-trip idempotency:** re-`push` with no local edits = **zero** remote writes; re-`pull` with unchanged remote = **zero** local rewrites.
+- **FR6 — Migration:** existing single `{file}.comments.md` sidecars convert to the `comments/` layout losslessly.
+
+### Non-functional invariants ("bidirectional, no clobber")
+- **NC1 — Append-only to remote:** docspan only ever *creates* comments/replies and *resolves/reopens*. It never updates or deletes remote comments/replies (anyone's, including the user's). Kills the whole "sync rewrote/lost a comment" class.
+- **NC2 — Un-pushed local additions are sacred:** `pull` never discards/overwrites a locally-authored, not-yet-pushed reply/comment.
+- **NC3 — Remote additions never clobber local:** `pull` merges by stable identity, never wholesale file regeneration.
+- **NC4 — Stable thread/reply identity:** every thread/reply addressable by Drive id; not-yet-pushed items carry an explicit "no id yet" marker.
+- **NC5 — Offline-testable:** all request-building/parsing/reconciliation unit-testable with fixtures, no network.
+- **NC6 — Crash-safety:** atomic writes (temp-then-rename, as `SyncState.save` does); a mid-push crash must not silently double-post (best-effort — R1).
+
+### Non-goals (v1)
+- Anchored/text-range placement of new comments (Drive ignores `anchor` on Workspace editor files — §2).
+- Editing/deleting anyone's existing remote comment/reply.
+- Rich formatting (comment `content` is plain text on write).
+- Confluence inline-comment write path (separate later effort).
+
+---
+
+## 2. Research findings — Drive comments/replies API
+
+Comments live on **Drive API v3**, not Docs v1. `GoogleDocsClient` already holds `drive_service` — no new wiring.
+
+| Capability | Method | Notes |
+|---|---|---|
+| List threads + replies | `comments.list(fileId, fields=…, pageToken)` | Paginated; must request nested `replies` + output-only fields |
+| Get one thread | `comments.get(fileId, commentId, fields=…)` | Cheap resolved/modifiedTime check |
+| Create top-level comment | `comments.create(fileId, body={content, quotedFileContent?, anchor?})` | `content` = plain text (write); `htmlContent` output-only |
+| Create reply | `replies.create(fileId, commentId, body={content})` | Same content semantics |
+| Resolve / reopen | `replies.create(fileId, commentId, body={action:"resolve"|"reopen", content?})` | Resolving = a reply with an action |
+| List replies | `replies.list(fileId, commentId)` | Usually unneeded — `comments.list` embeds replies |
+
+**Design-shaping limits:**
+- **`anchor` is ignored on Google Docs** — a new anchored comment renders as "Original content deleted" / no highlight. → new comments must be document-level/unanchored (ADR-004). *(High confidence — documented + reproduced.)*
+- **`content` plain text on write; `htmlContent` read-only** — no rich round-trip.
+- **Output-only fields need explicit `fields=`** (`id`, `createdTime`, `htmlContent`, `resolved`, nested `replies`).
+- **Editing/deleting others' items** → 403; avoided entirely per NC1.
+- **Scopes:** writing needs full `drive` scope. `PUSH_SCOPES` already has it → existing push tokens suffice; `drive.readonly` tokens can't write and must re-consent.
+- **Quoted selection is read-only context** — surfaced, never used for positioning writes.
+
+Stable identity = Drive comment/reply `id` (stable server strings). A not-yet-pushed local item has no server id → explicit empty-id + `pushed=false` marker (NC4), filled after `create`.
+
+Sources: [Manage comments and replies](https://developers.google.com/workspace/drive/api/guides/manage-comments) · [REST: comments](https://developers.google.com/workspace/drive/api/reference/rest/v3/comments) · [anchor "Original content deleted" issue](https://github.com/googleworkspace/cli/issues/169)
+
+---
+
+## 3. Design
+
+### 3.1 The `comments/` directory layout
+
+Replace the single regenerated `{local}.comments.md` blob with a directory beside the local file:
+
+```
+notes/spec.md
+notes/spec.comments/            ← COMMENTS_DIR_SUFFIX = ".comments"
+  t-8f3a2c.md                   ← one file per thread; filename = stable LOCAL id
+  local-4c9d.md                 ← a brand-new thread not yet pushed (no server id)
+```
+
+**Naming (ADR-002): filename = stable local id; server id in front matter.** Filename never changes across syncs (avoids git churn + rename races). New local thread = `local-<short-uuid>.md`; after push it keeps the filename but gains `remote_id`. A `remote_id → filename` index lives in state for O(1) reconcile.
+
+**Per-thread file — YAML front matter + id-addressed marker blocks:**
+
+```markdown
+---
+thread: t-8f3a2c            # stable local id (== filename stem), never changes
+remote_id: "AAAABBBBcomment"  # Drive comment id; null until pushed
+resolved: false
+author: "Alice <alice@ex.com>"
+created: 2026-07-16T10:00:00Z
+quoted: "the p50 latency figure"   # read-only context
+anchored: false             # informational; Docs ignores anchor
+---
+
+<!-- comment id=AAAABBBBcomment author="Alice" created=... pushed=true -->
+Where does the p50 number come from?
+
+<!-- reply id=CCCCreply author="Bob" created=... pushed=true -->
+From the June dashboard.
+
+<!-- reply id= author=me created=... pushed=false -->
+I'll switch this to p99 and cite the source.
+```
+
+- **`pushed=false` + empty `id=`** is the sole "net-new local, push me" signal (NC4).
+- Block body = text between one marker and the next. Adding a reply = appending a `pushed=false` block (`docspan comments reply <thread>` scaffolds it).
+- After `create`, push rewrites **only that block's marker** (fills id, `pushed=true`) + the file's `remote_id`/`resolved` — nothing else touched.
+
+### 3.2 Identity & sync-state
+
+Comments are structured, id-bearing records → reconciled **by identity**, not the line-based `three_way_merge` used for doc bodies (ADR-003). Keep the three-way *philosophy* (base/ours/theirs) at thread+reply granularity.
+
+Extend the existing state store:
+- `comments` section in `MappingState` (or sibling keyed by local path) in `.markgate-state.json`:
+  ```jsonc
+  "comments": {
+    "index": { "AAAABBBBcomment": "t-8f3a2c" },   // remote_id → filename stem
+    "base_snapshot_hash": "<sha256>"               // pointer into base store
+  }
+  ```
+- Comments base snapshot in the content-addressed base store (reuse `save_base_content`/`get_base_content`), under `.markgate-base/comments/`:
+  ```jsonc
+  { "threads": { "AAAABBBBcomment": { "resolved": false, "replies": ["CCCCreply"], "content_hash": "…" } } }
+  ```
+  This snapshot is the **base**: `base` = last-synced remote, `theirs` = current `comments.list`, `ours` = local files.
+
+### 3.3 Push semantics
+
+`orchestrate_push` gains a comments pass (guarded by `comments_mode != off`; push-direction only):
+1. Parse every thread file.
+2. Collect actionable items (stable order — comments before replies, oldest first):
+   - `pushed=false` block on a thread with null `remote_id` → `comments.create` (unanchored); store id, update index, mark pushed.
+   - `pushed=false` reply under a thread with `remote_id` → `replies.create`; fill id, pushed.
+   - Front-matter `resolved` flipped vs base + user asked → `replies.create(action=resolve|reopen)`.
+3. **NC1:** only create + resolve/reopen calls. No update/delete.
+4. **Persist after each create** → idempotent re-runs (FR5), bounded crash window (R1).
+
+### 3.4 Pull semantics (anti-clobber core)
+
+`orchestrate_pull` gains a reconcile pass:
+1. `comments.list` (paginated, nested replies/resolved/quoted) → **theirs**.
+2. Load **base** snapshot + local files (**ours**).
+3. Reconcile per thread by `remote_id`, then per reply by reply id:
+
+| Case (by id) | Action | Invariant |
+|---|---|---|
+| Thread in theirs, not base/local | Create local thread file | — |
+| Reply id in theirs, not local | **Append** reply block (`pushed=true`) | NC3 |
+| Local block `pushed=false` | **Preserve verbatim** | NC2 |
+| `resolved` changed in theirs | Update front-matter | — |
+| Remote body edited (id in base+theirs, hash differs) | Replace **only that block's** body | NC1/NC3 |
+| Thread in base, absent from theirs (deleted remotely) | Mark `deleted: true` (never `rm`) | NC2 |
+
+4. Order remote by `createdTime`; local `pushed=false` blocks sort last.
+5. Write new base snapshot = current remote; update index.
+
+A **structured merge keyed by id** — the anti-clobber replacement for the regenerated blob.
+
+### 3.5 Migration from `{file}.comments.md`
+- New config `comments_mode: dir | sidecar | off` (replaces boolean `pull_comments`; `true` → `sidecar` w/ deprecation note).
+- First `dir`-mode run: if the old sidecar exists, regenerate the `comments/` dir from remote (authoritative; the old blob was read-only so nothing lost), rename old → `.bak`.
+- `docspan comments migrate [path]` (dry-runnable). Add `COMMENTS_DIR_SUFFIX = ".comments"` in `core/paths.py`.
+
+---
+
+## 4. ADRs
+
+- **ADR-001 — Directory-per-thread over single regenerated sidecar.** The single blob regenerates wholesale on every pull → can't safely hold user edits. Per-thread files give stable handles, surgical appends, localized conflicts.
+- **ADR-002 — Filename = stable local id; server id in front matter.** Rejected filename=server-id (rename on first push → git churn, identity break, half-push races).
+- **ADR-003 — Structured id-keyed reconciliation, not line-based merge.** `merge3` reused only for a rare edited body within one block. Line merge corrupts identity-bearing records / interleaves replies.
+- **ADR-004 — v1 = replies + resolve + unanchored new comments; no anchored creation.** Drive ignores `anchor` on Docs; anchored create renders "Original content deleted." Ship replies + resolve first; new comments (Phase 3) unanchored, flagged, documented.
+
+---
+
+## 5. Phased implementation plan
+
+- **Phase 0 — Directory refactor (read-only).** `comments/` layout, marker-block serializer/parser (round-trip tested), `comments_mode` + migration, `COMMENTS_DIR_SUFFIX`. Pull still regenerates from remote (safe). Smallest useful step.
+- **Phase 1 — Bidirectional replies + reconcile-aware pull (SHIP TOGETHER).** `client.create_reply`/resolve, push comments-pass, base snapshot, id-keyed reconcile pull (§3.4), `docspan comments reply`. *Push and reconcile-pull must ship in one release* — shipping push while pull still regenerates would clobber un-pushed local replies (violates NC2).
+- **Phase 2 — New unanchored top-level comments.** `client.create_comment` + push, behind `comments_new: true`, limitation surfaced. `docspan comments new`.
+- **Phase 3 — Robustness & polish.** Remote-deletion UX, resolve edge cases, crash-window dedupe (R1), `docspan comments status`. Later: Confluence parity (separate plan).
+
+---
+
+## 6. Test strategy (offline-first)
+
+Mirror `tests/test_orchestrator.py` (in-memory fake, `tmp_path`, no network):
+- Fixtures: captured `comments.list` JSON (open+resolved, nested replies, quoted, multi-page). Assert `fields` mask requests nested replies + output-only fields.
+- Serializer/parser round-trip byte-stable; empty-id `pushed=false` markers survive; hand-appended reply parses.
+- Reconcile as a **pure table-driven function** `(base, remote, local) → (files, action_plan)` covering every §3.4 row — especially **local-unpushed-preserved (NC2)**.
+- Push planner → ordered create/reply/resolve calls against a `FakeDriveComments` double; payload shapes (plain-text content; resolve `action`); **second run = zero calls (FR5)**.
+- Migration: old sidecar → dir generated, `.bak` created, no loss.
+- Scope guard: read-only token → clear "re-auth for write", not raw 403.
+
+---
+
+## 7. Risks & open questions
+
+- **R1 — Crash-window double-post.** No idempotency key on Drive comments; a create that succeeds then crashes before local persist re-posts next run. *Mitigation:* persist after each create; Phase 3 dedupe on next pull. **Open:** acceptable for v1?
+- **R2 — `me` attribution** for un-pushed blocks; confirm no display-name reconcile needed (cosmetic).
+- **R3 — Resolve permissions** may 403 for non-authors depending on sharing; best-effort, per-thread report, never fail whole push.
+- **R4 — Unanchored comments UX** (Phase 2): document-level only. **Operator decision:** acceptable, or omit new-comment creation from v1?
+- **R5 — Large threads / pagination cost.** Reuse `_with_backoff`; consider a `modifiedTime`-gated skip. **Open:** cheap "any comments changed?" probe? (none first-class).
+- **R6 — Ordering churn** when local blocks gain ids; ensure minimal diff.
+
+---
+
+## 8. Adversarial self-review (fixes folded in)
+
+- **Clobber window between push and pull** → Phase 1 ships push + reconcile-pull together; Phase 0 stays read-only.
+- **Filename-as-server-id churn/races** → ADR-002 stable local id.
+- **Line-merge on comments corrupts/interleaves** → ADR-003 id-keyed reconcile.
+- **Silent loss on remote deletion** → mark `deleted: true`, never `rm`.
+- **Idempotency false-confidence** → persist after each create; residual window = R1.
+- **Scope trap** (readonly token silently fails writes) → explicit scope check + re-auth message.
+- **Broken anchored feature** → ADR-004 unanchored-only, documented.

docspan-0.2.0/project_plans/gdocs-tables-inline-styles/plan.md

@@ -0,0 +1,59 @@
+# Plan: Google Docs table push + inline styles on insert
+
+## Problem
+
+The Google Docs push path drops two things, both blocking real-world design-doc use:
+
+1. **Inline styles/links are lost on insert.** `MarkdownToParagraphParser` flattens inline
+   tokens to plain text (no spans), and `DocsRequestBuilder._make_insert_requests` never applies
+   text styles — the `_make_text_style_requests` helper exists but is unused. So bold, italic,
+   inline code, and **links** vanish on push.
+2. **Tables are dropped entirely.** The markdown parser skips `table` tokens and
+   `DocsStructureParser` skips table elements (`# table … silently skipped`), so markdown tables
+   never reach the doc, and a doc that already has a table can't be diffed against.
+
+## Goals
+
+- Preserve inline **links, bold, italic, monospace** when inserting/replacing paragraphs.
+- Render markdown tables as real Google Docs tables on push.
+- Parse existing Google Docs tables back into the node model so the structural diff is
+  **idempotent** (pushing an unchanged table produces no requests; it isn't re-inserted).
+
+## Non-goals (v1)
+
+- Rich inline styling *inside* table cells — v1 fills cells with plain text (cell links/bold become
+  plain text). Prose links/formatting are fully preserved. Rich cells are a fast-follow.
+- Image push, nested tables, cell merges.
+
+## Design
+
+### Inline styles (Part 1)
+- Parser: add `_spans_from_inline(children, …)` that walks mistune inline tokens
+  (`text`/`strong`/`emphasis`/`link`/`codespan`) into ordered `TextSpan`s, propagating
+  bold/italic/link/monospace through nesting. `node.text = "".join(span.text)` so the existing
+  diff key (keyed on text) is unchanged.
+- Builder: in `_make_insert_requests`, after `insertText`, walk `node.spans`, compute UTF-16
+  offsets, and emit `updateTextStyle` (via `_make_text_style_requests`) for any styled span.
+
+### Tables (Part 2)
+- New `DocsTableNode(rows: List[List[str]], start_index, end_index)` in the structure module.
+- Parser emits `DocsTableNode` for `table` tokens (header row + body rows, cell = plain text).
+- `DocsStructureParser` parses live `table` elements into `DocsTableNode` (rows from
+  `table.tableRows[].tableCells[].content` paragraphs), with real start/end indices.
+- `DocsRequestBuilder.build` now diffs a mixed `List[Union[DocsParagraphNode, DocsTableNode]]`.
+  Table diff key = `("__table__", tuple(tuple(row) for row in rows))`.
+  - **insert** → emit `insertTable` (rows×cols) at the insert index (Pass 1).
+  - **delete** → `deleteContentRange` over the table span.
+  - **equal** → no request (idempotent).
+- **Cell fill is two-pass** (robust vs. fragile predicted indices): Pass 1 inserts empty tables;
+  `backend.push` re-fetches the doc, and `build_table_fill_requests(doc, queued_tables)` locates
+  empty tables in document order and emits reverse-ordered `insertText` per cell. Cell indices come
+  from the *real* re-fetched JSON, so no index guessing.
+
+## Verification
+
+- Unit tests (no network) for: span extraction, styled-insert requests, markdown→table node,
+  live-table→node parsing, table insert/delete/equal diffing, and cell-fill request generation
+  against a sample table JSON.
+- **Live smoke test still required** before trusting cell fill end-to-end — needs docspan Google
+  credentials (service account or OAuth token). Tracked as the last step.