literary-gdrive-management - SKILL.md Agent Skill

name: literary-gdrive-management description: "Manage Google Drive sync for literary-compilation. Use when asked to mirror the Literary Compilation library to Drive, build styled PDFs, sync data markdown, force rebuild PDFs, dry-run Drive sync, authenticate Google Drive, inspect literary gdrive settings, or use scripts/mirror_library_to_drive.py."

Google Drive Library Mirror Management

When To Use

Use this skill for literary-compilation tasks involving the Google Drive PDF mirror, especially:

Building styled PDFs from Markdown files under data/.
Syncing one document, a folder subset, or the whole library to Drive.
Running a dry-run before an upload.
Refreshing OAuth credentials or validating Drive authentication.
Troubleshooting scripts/mirror_library_to_drive.py.
Deciding whether to use --only, --force, --dry-run, or --delete-remote-extras.

This skill is for the library PDF mirror. It is not for large generated artifact archives from other repositories.

Script

Use the repository script:

python scripts/mirror_library_to_drive.py

The script converts Markdown files under data/ into styled PDFs under:

output/library_pdf_mirror/

Then it mirrors the PDF folder structure to the configured Google Drive folder.

Default auth files:

secrets/google_drive_oauth_client.json
secrets/google_drive_token.json
secrets/google_drive.env

The Drive folder ID can be supplied with --drive-root-id or by setting GOOGLE_DRIVE_ROOT_ID in secrets/google_drive.env.

Standard Workflow

Check Git status first, and do not touch unrelated user files:
```
git status --short --branch
```

For a single updated document, prefer --only with the path relative to data/:

python scripts/mirror_library_to_drive.py --only "03_Biblical_Scholarship/filename.md"

Force rebuild a single PDF when styling, template, links, or cached output may be stale:
```
python scripts/mirror_library_to_drive.py --only "path/to/file.md" --force
```

Dry-run before unfamiliar or broad changes:

python scripts/mirror_library_to_drive.py --only "path/to/file.md" --dry-run

Sync the whole library only when intended, because it can be slow:
```
python scripts/mirror_library_to_drive.py
```

Authenticate without building or uploading:

python scripts/mirror_library_to_drive.py --auth-only

Path Rules

--only paths are relative to data/, not the repository root.
--only must point to a Markdown file.
Use forward slashes in paths for portability.
The script validates that --only stays inside data/.

Examples:

python scripts/mirror_library_to_drive.py --only "00_Master_Theses/Some Thesis.md" --force
python scripts/mirror_library_to_drive.py --only "08_Correspondential_Texts/Some Document.md" --dry-run

Safety Rules

Ask for explicit confirmation before using --delete-remote-extras.
Do not use a broad full-library sync when a single --only sync will satisfy the request.
Do not commit or inspect files under secrets/ beyond checking whether required paths exist.
Do not treat generated PDFs under output/library_pdf_mirror/ as source material.
If Drive API reports accessNotConfigured, tell the user the Google Drive API must be enabled for the OAuth project.

Troubleshooting

If Chromium is missing:

python -m playwright install chromium

If the script reports missing Drive folder ID, provide --drive-root-id or update:

secrets/google_drive.env

If OAuth is expired or missing, run:

python scripts/mirror_library_to_drive.py --auth-only

If a file is not found with --only, confirm the path is relative to data/ and ends in .md.