gdocs-audit-report

Google Docs Security Audit Report

Overview

This skill provides patterns, constants, and gotcha-avoidance for building and maintaining security audit reports in Google Docs using the Docs API (service account auth). It encodes hard-won lessons around index drift, code styling multi-pass, paragraph vs text backgrounds, heading anchor URLs, and cross-reference linking.

Always read references/api-patterns.md and references/formatting-standards.md before writing any script.

Workflow

1. Auth          → make_token() from scripts/gdocs_auth.py
2. get_doc()     → fresh snapshot before EVERY batch of edits
3. Build ops     → sort ALL ops highest-index-first
4. do_batch()    → send in chunks of ≤50
5. Verify        → get_doc() again and spot-check changed ranges

Critical Gotchas (read these first)

1. Index drift

Any insert/delete shifts every index above it. Always sort ops high→low. Always get_doc() fresh.

2. Text bg ≠ paragraph bg

updateTextStyle.backgroundColor only covers character width - leaves white gaps between lines in code blocks. Use updateParagraphStyle.shading.backgroundColor + spaceAbove/Below: 0 for full-width code block backgrounds.

3. headingId already has h. prefix

Anchor URL = #heading={headingId} - not #heading=h.{headingId}.

4. Code styling needs multiple passes

After updateTextStyle splits a run, new unstyled sub-runs appear. Always do a second full-doc re-scan after the first styling pass.

5. Sort code terms longest-first

Prevents maxRelayFeeBPS matching before assetConfig.maxRelayFeeBPS and leaving a partial un-styled prefix.

6. Backtick removal order (per segment, high→low)

Delete closing backtick → style inner → delete opening backtick - all in one batch.

7. Bullet conversion

createParagraphBullets does not change indices. Then deleteContentRange the - prefix high→low in a second batch.

8. Cross-reference links: skip only already-linked runs

Scan ALL runs for X-NN regex - only skip runs where textStyle.link is already set. Do NOT also filter by font (Courier runs can contain xrefs too).