## TL;DR
Restore the deleted files from git first, then fence generated pages into their own directory that the sync is allowed to wipe, with everything else off-limits. The agent deleted your docs because the sync treated the whole docs tree as its scratch space. Restore, then fence.

```text
docs agent failed: deleted hand-written docs while syncing generated pages
```

## Steps
1. List what was deleted: run `git status --short` right after the sync and note every D entry, or `git log --diff-filter=D --name-only -1` if it was committed. Expected: a concrete list of deleted paths.
2. Restore them: for uncommitted deletions run `git restore -- [deleted-path]` per file; for a committed bad sync, revert the commit. Expected: `git status --short` shows the files back and the content matches the pre-sync version.
3. Separate generated from hand-written: move all generated pages under one fenced directory (for example docs/api-generated) with a marker file noting it is machine-managed. Hand-written docs live everywhere else.
4. Constrain the sync: configure the agent so deletions are only allowed inside the fenced directory, and require it to print a deletion preview and stop for confirmation before removing anything outside it. Expected: a dry run lists deletions without performing them.
5. Rerun the sync and verify: `git status --short` should show changes only under the fenced directory. Expected: no hand-written file is touched.

## Use this when
- hand-written docs disappear after an agent sync run
- git shows D entries for docs you wrote by hand
- generated and hand-written pages currently share one directory

## Not for this skill when
- the agent overwrote file contents instead of deleting files (restore from git, then fix the writer)
- files were deleted by a human or a different tool
- you actually want the sync to prune stale hand-written pages (then make that an explicit, confirmed step)

## Variant phrasings
- docs agent wiped my markdown files during sync
- generated docs sync deleted hand-written pages
- agent removed docs it should not have touched

## Why it happens
The sync logic was "make the docs tree match what I generated," which is correct for generated pages and destructive for everything else. With no boundary between machine-managed and hand-written files, pruning stale generated pages also prunes your work.

## Edge cases
- If other work is mixed into the same commit as the bad sync, revert selectively instead of reverting the whole commit.
- Restoring the whole tree can also drop legitimate changes: prefer restoring only the deleted paths.
- Renamed files look like delete-plus-add: confirm they are real deletions before restoring.
- Back up the restored files before rerunning the sync, until the fence has proven itself once.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_y_43KgmxdwZd-k79xu9stA