# Rules for agents

> The rules an AI agent follows when it frees disk space with census. Written for the agent to read, and complete on its own.

Disk Census deletes permanently: nothing goes to the Trash. These rules keep every deletion a choice the person made. If you are an agent, follow them exactly; the steps for each request are in [The workflow](https://diskcensus.com/docs/agents/workflow.md).

## Before you run anything

- Run `census version --json`. If `census` isn't found, tell the person Disk Census isn't installed or isn't on `PATH`, and stop.
- Use the whole startup drive, the default. Add `--path FOLDER` only when the person names a folder, and keep the same scope for every step.
- Pass `--json` to every command. Read `exit_code` and `errors` from the JSON, not the text.

## What needs the person's yes

| Action | Approval |
| --- | --- |
| Queries: `breakdown`, `top`, `findings`, `large`, `duplicates`, `apps`, `app`, `review --json`, `maintain --json`, `empty-trash --json` | None. They only read. |
| `census clean --safe` | The person asked you to clean junk, caches or build output. That request is the approval; don't ask again. |
| `census apply FILE` | The person chose the items, then said yes to "Permanently delete these N items (X GB)?" |
| `census uninstall NAME --yes` | The person said yes to "Uninstall NAME and delete its data (X GB)?" |
| `census maintain TASK ... --yes` | The person chose the tasks. |
| `census optimize --yes` | The person asked to optimize or clean up everything, after you showed what it does. |
| `census empty-trash --yes` | The person asked to empty the Trash, then said yes to "Permanently delete N items (X GB) from the Trash?" |

When you list items for the person to choose from, don't suggest any. The person decides.

## Never

- Never put a path in a selection file that `review --json`, `duplicates --json` or `large --json` didn't list. census refuses it anyway.
- Never pass `--safe` unless the person asked you to clean, and never pass `--yes` to `uninstall` before the person said yes.
- Never delete files with `rm`, `trash`, Finder, or any tool other than census's own commands.
- Never run census with `sudo`. It refuses to delete as root.
- Never run `census maintain` with tasks, or `census optimize`, before the person said yes.
- Never retry a failed `apply` with different paths without asking the person again.
- Never empty the Trash as part of cleaning junk or optimizing.
- Never quit an app yourself. On `app_running`, ask the person to quit it.
- Never delete an AI agent's history. census lists it as `keep` and never offers it.

## Exit codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `0` | Done. Skipped items are normal. | Report the result. |
| `1` | Bad request: `confirmation_required`, `invalid_selection`, `review_stale`, `run_as_root`, `app_running`, `needs_admin`, `system_app`, `not_removable`. Nothing was deleted. | On `review_stale`, run `census review --json` again and show the new list. Otherwise report `errors[0].message`. |
| `2` | Operational failure: `cleanup_running`, `cleanup_failed`, `scan_failed`, `trash_unreadable`. | On `cleanup_running`, wait; don't retry in a loop. Otherwise report the message. |
| `4` | `partial_cleanup`: some items couldn't be fully deleted. `app_not_removed`: the app stayed. | Report each item whose `outcome.result` isn't `deleted`, or the reason the app stayed. |
| `7` | `no_review`: nothing to apply. | Run `census review --json` first. |
| `130` | Cancelled. | Tell the person. What was deleted so far is in the audit log. |

## Why these rules hold

census doesn't rely on you for safety. Whatever you run, `apply` deletes only paths census itself listed, every item is rechecked on a fresh scan, items in use are skipped, protected and synced folders are refused, and nothing runs as root. The rules above make sure that what census does delete is what the person chose.