docs(refactor): clean up notes

docs/refactor/README.md

@@ -0,0 +1,19 @@
+---
+summary: "Refactor notes (implementation status + next wins)"
+read_when:
+  - Touching exports/output/templates
+  - Planning cleanup work
+---
+
+# Refactor notes
+
+Shipped (today)
+
+- `exports.md`: Drive-backed export command pattern (`docs|slides|sheets`).
+- `output.md`: shared table + paging helpers.
+- `templates.md`: googleauth HTML templates via `//go:embed`.
+
+Backlog / next wins
+
+- `options.md`: ideas; pick + execute when touching adjacent code.
+

docs/refactor/exports.md

@@ -1,11 +1,18 @@
+---
+summary: "Drive-backed export commands (Docs/Slides/Sheets)"
+read_when:
+  - Adding a new Drive-backed export command
+  - Changing `--format` / `--out` behavior
+---
+
 # Exports (Drive-backed)
 
-Goal: one implementation for “export Google *Thing* via Drive” commands.
+Goal: one implementation for “export Google *Thing* via Drive”.
 
 ## Current pattern
 
 - Shared builder: `internal/cmd/export_via_drive.go:newExportViaDriveCmd`
-- Shared download: `internal/cmd/drive_download.go:downloadDriveFile` (handles Drive “native” exports + normal files)
+- Shared download: `internal/cmd/drive.go:downloadDriveFile` (handles Drive “native” exports + normal files)
 
 Each service command is a thin wrapper:
 
@@ -17,7 +24,8 @@ Each service command is a thin wrapper:
 
 - Arg is always the Drive file id (Doc/Sheet/Slides id).
 - Type guard: compare `mimeType` and error with `file is not a <KindLabel> (mimeType="...")`.
-- `--out` defaults to the gogcli config dir; `--out` can be dir or explicit file path (via existing Drive download logic).
+- `--out` defaults to `$(os.UserConfigDir())/gogcli/drive-downloads/` (via `internal/config:EnsureDriveDownloadsDir`).
+- `--out` can be dir or explicit file path (via `internal/cmd/drive_download_helpers.go:resolveDriveDownloadDestPath`).
 - Output
   - `--json`: `{ "path": "...", "size": <bytes> }`
   - text: `path\t...` / `size\t...`
@@ -27,4 +35,3 @@ Each service command is a thin wrapper:
 1) Pick expected Drive mime type + allowed formats.
 2) Add a new `newXExportCmd` calling `newExportViaDriveCmd(...)`.
 3) Add/extend tests in `internal/cmd/execute_drive_*_test.go` style (fake Drive server).
-

docs/refactor/options.md

@@ -1,3 +1,10 @@
+---
+summary: "Refactor options (next wins)"
+read_when:
+  - Planning cleanup work
+  - Touching retry/logging/output plumbing
+---
+
 # Refactor options (next wins)
 
 Small wins
@@ -16,4 +23,3 @@ Bigger wins
 
 - API client retry unification: one retry stack (transport vs explicit); delete the other; push logs behind `--verbose`.
 - Command grouping / UX: consolidate “download/export” story; ensure help text + flags match across services.
-

docs/refactor/output.md

@@ -1,3 +1,10 @@
+---
+summary: "Output helpers (tables + paging)"
+read_when:
+  - Adding/changing list commands
+  - Touching pagination output
+---
+
 # Output helpers (tables + paging)
 
 Goal: kill copy/paste; keep output consistent.
@@ -20,4 +27,3 @@ Use `internal/cmd/output_helpers.go:printNextPageHint(u, token)`:
 
 - prints to stderr
 - exact format (tests depend on it): `# Next page: --page <token>`
-

docs/refactor/templates.md

@@ -1,3 +1,10 @@
+---
+summary: "googleauth templates via `//go:embed`"
+read_when:
+  - Editing auth UI
+  - Touching template parsing/escaping issues
+---
+
 # googleauth templates (embed)
 
 Problem: huge `templates*.go` files, noisy diffs, hard to edit.
@@ -16,5 +23,4 @@ Problem: huge `templates*.go` files, noisy diffs, hard to edit.
 ## Editing flow
 
 - Edit the HTML files directly.
-- Run `make test` (or `go test ./...`) to confirm templates still parse + handlers still render.
-
+- Run `go test ./...` to confirm templates parse + execute (tests cover this).