---
name: our-gdrive-organizer
description: |
  Organize a Google Drive folder under OurDigital conventions: refresh root
  README.md index, refresh per-subfolder README.md meta files, propose renames
  for files using the old D.intelligence brand, and propose moves for cluttered
  files (screenshots at the wrong level, temp/partial downloads).

  Triggers:
  - "organize the Drive folder", "organize this folder"
  - "refresh the index", "rescan the folder", "update README"
  - "clean up cluttered files", "propose renames"
  - "/organize", "/organize-drive", "/our-gdrive-organizer"

  Default target is the current working directory. Generalized to work on any
  2nd-level subfolder of the user's Google Drive Stream (My Drive/00_..., 01_...,
  02_..., etc.) — not specific to one folder.
version: "1.0"
author: OurDigital
environment: Code
---

# our-gdrive-organizer (Code)

Walks a target directory (3 levels deep), refreshes the index README, proposes
renames + moves under OurDigital naming conventions, and optionally applies.

Source of truth for the conventions: `../shared/conventions.md`.

## Activation

The user wants to organize one of their Drive folders. Cues:
- An explicit ask: "organize", "refresh index", "rename per convention", "scan for changes"
- The user is sitting inside a 2nd-level Drive folder (`~/Library/CloudStorage/GoogleDrive-*/My Drive/NN_*/`)
- Slash invocation: `/organize`, `/our-gdrive-organizer`

## Workflow

### Step 1 — Run dry-run, then summarize

```bash
~/.local/bin/our-gdrive-organize "$TARGET"
```

(`$TARGET` defaults to cwd; pass an absolute path for a specific folder.)

The script writes the README index immediately (idempotent — skips when no
structural change), but never renames or moves files without `--apply`.

Read the report and tell the user, in plain language:
- How many structural changes were folded into the README
- Each rename proposal (old → new, reason)
- Each move proposal (file → destination subfolder, reason)
- Subfolders that were skipped because they're "sensitive" (`04_Case Studies`,
  `99_Project Archive`, `*Archive*`, `진단*`)

### Step 2 — Confirm with user before applying

If the user says go ahead (or "apply", "yes", "do it"):

```bash
~/.local/bin/our-gdrive-organize "$TARGET" --apply
```

If the user wants only part of the work:

```bash
~/.local/bin/our-gdrive-organize "$TARGET" --scope rename --apply
~/.local/bin/our-gdrive-organize "$TARGET" --scope move --apply
~/.local/bin/our-gdrive-organize "$TARGET" --scope index           # always writes
~/.local/bin/our-gdrive-organize "$TARGET" --scope subreadmes      # always writes
```

### Step 3 — Verify

After applying, run the dry-run once more and confirm the proposal list is
empty (or only contains items the user explicitly skipped).

## Important guardrails

- **Never rename or move files inside `04_Case Studies/`, `99_Project Archive/`,
  any `*Archive*` folder, or any folder starting with `진단`.** Those contain
  real client engagement records that must keep their original filenames.
- The script's rename/move rules live in `code/organizer.py` near the top of
  the file (`RENAME_RULES`, `MOVE_RULES`, `SENSITIVE_SUBFOLDER_PATTERNS`). If
  the user asks to add or change a rule, edit there and re-run.
- Filename renames on `.gsheet` / `.gdoc` stub files only change the local
  filename — the actual Google Drive document and its sharing links are
  preserved (the stub holds a Doc ID, not the content).

## What the script does NOT do

- Does not edit cell content inside `.gsheet` / `.gdoc` / `.xlsx` / `.pdf` —
  only local-filesystem renames. Cell-level neutralization stays a manual task.
- Does not delete anything.
- Does not modify the manually-curated Topics / Notes sections of the root
  README — only the AUTO-STRUCTURE block.
- Does not categorize files by reading their **content** — for that, use the
  Content-based reorganization workflow below.

## Folder-rename support

The script proposes folder renames (in addition to file renames) using the
same `RENAME_RULES`. Guardrails:
- **Top-level subfolders are NEVER renamed automatically.** Names like
  `00_Brand Management/` or `02_SEO Audit Toolkit/` are user-curated
  practice areas. If the user wants one renamed, do it as a one-off `mv`.
- Sensitive folders are skipped entirely (not renamed, not recursed into).
- Eligible folders: depth-2 and deeper (e.g.,
  `00_Brand Management/D.intelligence SEO Audit/` → `…/OurDigital SEO Audit/`).

When `--scope rename --apply` runs, file renames execute first, then folder
renames — order matters because renaming a folder first would invalidate
the file rename paths inside it.

## Content-based reorganization (interactive)

The script handles deterministic naming-pattern work. For judgment calls
(which folder does this file truly belong in?), use this workflow.

### When to use

The user says any of:
- "look at the contents and reorganize"
- "this folder feels cluttered, suggest a better layout"
- "categorize the files in {subfolder}"
- "audit my folder structure"

Or you notice during a regular `/organize` run that:
- A subfolder root has many loose files that should plausibly be grouped
- Files appear duplicated across subfolders
- Filenames hint at content that doesn't match their location

### Workflow

1. **Anchor yourself** — read the patterns library before proposing anything:
   - `../shared/patterns/canonical-folders.md` — what well-organized shapes look like
   - `../shared/patterns/canonical-files.md` — what well-named files look like
   - `../shared/patterns/categorization-rules.md` — IF→THEN placement rules
   - `../shared/patterns/gotchas.md` — known edge cases

   These are the gotcha library. Re-read them every session — they grow over time.

2. **Pick one subfolder at a time.** Don't try to reorganize an entire
   2nd-level folder in one pass — too much for the user to review.

3. **Sample file contents.** For each file in the chosen subfolder:
   - Markdown / txt / json: `Read` directly.
   - `.gsheet` / `.gdoc` stubs: read the JSON to extract the doc_id, but
     accept that you can't see actual cell content. Use the FILENAME
     pattern + adjacent context.
   - PDFs / .docx / .pptx / .xlsx: you can't read content with stdlib.
     Either ask the user to summarize, or skip and rely on filename.
   - For each file, note 1–2 sentences: what's it about, where would it
     belong by content?

4. **Build proposals**, grouped by destination:
   ```
   Move from `02_SEO Audit Toolkit/` → `04_Case Studies/`:
   - `signed-acme-contract.pdf` (real client name + signed contract content)

   Move from `02_SEO Audit Toolkit/` → `05_Working Template/`:
   - `OurDigital-OOO Audit Template.gsheet` (placeholder name → template)
   ```

5. **Present one batch (one source folder) at a time.** Ask:
   "Should I apply these N moves from `{source}/`? Yes / No / partial (which)."

6. **Apply via `Bash mv`** for each confirmed move:
   ```bash
   mv "/path/to/source/file" "/path/to/destination/file"
   ```
   Then refresh the index:
   ```bash
   our-gdrive-organize "$TARGET" --scope index
   ```

7. **Capture new gotchas.** If you encountered an ambiguous case the
   patterns library didn't cover, append it to
   `../shared/patterns/gotchas.md` before ending the session — that's how
   the system learns.

### Sensitive-folder reminder

When proposing moves in content-based mode, the same guardrails apply:
**never propose moving files INTO or OUT OF**:
- `04_Case Studies/`
- `99_Project Archive/`
- Any `*Archive*` folder
- Any folder starting with `진단`

If you notice something in those folders that looks misplaced, flag it to
the user as a manual review item — don't propose an automated move.

## When the user asks to extend

To add a new rename rule, edit `RENAME_RULES` in `code/organizer.py`:

```python
(re.compile(r"oldpattern", re.I), "newpattern", "human-readable reason"),
```

To add a new move rule, edit `MOVE_RULES`:

```python
(re.compile(r"^pattern\.ext$"), "destination_subfolder", "reason"),
```

Update `../shared/conventions.md` whenever rules change.