# AI Agent Usage Guide

Use this guide when asking Codex, ChatGPT, GitHub Copilot agents, or project-local AI agents to use TagTamer for Azure tag governance across multiple products, customers, tenants, subscriptions, or environments.

## Goal

TagTamer should let each Azure estate keep its own tag inventory, model, mapping decisions, rollback snapshots, and deployment package while still using the same TagTamer analytics and cleanup workflow.

An estate can be a product, customer, tenant, landing zone, subscription group, management group, sovereign cloud boundary, or environment family. Examples:

- `rmm-prod`
- `readairr-dev`
- `vanroojen-shared-services`
- `customer-a-gov`
- `spotstarter-prod`

## Estate Separation Rules

- Treat each estate as a hard boundary unless the operator explicitly asks for a combined portfolio analysis.
- Do not mix Resource Graph exports from different tenants, subscriptions, customers, or project estates in one TagTamer inventory file.
- Do not reuse rollback snapshots across estates.
- Do not deploy an Azure Policy package generated for one estate into another estate without reopening the correct saved settings and re-exporting the package.
- Keep estate names in exported file names, commit messages, handoffs, and operational notes.
- Use the same canonical tag policy across estates only when that is the intended governance standard.
- If a shared corporate tag model exists, copy or import it into each estate-specific saved settings file, then adjust aliases and defaults per estate.

## Recommended File Naming

Use predictable file names so agents and humans can tell inventory, settings, plans, and rollback files apart.

```text
tagtamer.<estate-id>.inventory.json
tagtamer.<estate-id>.saved-settings.json
tagtamer.<estate-id>.mapping.csv
tagtamer.<estate-id>.plan.json
tagtamer.<estate-id>.rollback.<YYYY-MM-DD>.json
tagtamer.<estate-id>.policy-package.zip
```

Examples:

```text
tagtamer.rmm-prod.inventory.json
tagtamer.rmm-prod.saved-settings.json
tagtamer.rmm-prod.rollback.2026-05-27.json
tagtamer.customer-a-gov.policy-package.zip
```

## Agent Workflow

1. Identify the estate before opening, importing, or generating anything.
2. Open `https://tagtamer.vanroojen.com/`.
3. Load the estate-specific `tagtamer.<estate-id>.saved-settings.json` if it exists.
4. Generate or reuse the Resource Graph export command for that estate.
5. Save inventory as `tagtamer.<estate-id>.inventory.json`.
6. Import only that estate's inventory into TagTamer.
7. Review Analyze and Map results for that estate.
8. Export a rollback snapshot before generating apply scripts.
9. Export the policy package with the estate id in the filename.
10. Record the estate id, cloud, tenant/subscription scope, generated package, rollback file, and deployment status in the project handoff.

## Shared Analytics UI Pattern

The GA app is a no-sign-in browser UI. Use the same TagTamer UI for every estate, but load one estate at a time.

For cross-estate analytics, keep the source files separate and aggregate only exported summaries or plans that include the estate id. A future portfolio dashboard can safely group rows by `estateId`, `cloud`, `tenantAlias`, `subscriptionId`, `resourceGroup`, canonical key, and canonical value.

Recommended portfolio columns:

```text
estateId
estateName
cloud
tenantAlias
scopeType
scopeId
subscriptionId
resourceGroup
resourceId
resourceName
tagKey
tagValue
canonicalKey
canonicalValue
mappingAction
policyBehavior
changedByPackage
rollbackSnapshot
observedAt
```

## Prompt For Project Agents

Copy this prompt into another project when you want its agent to use TagTamer without crossing estate boundaries:

```text
Use TagTamer for this project's Azure tag governance. Treat this project as estate `<estate-id>`.

Do not combine this estate's inventory, mappings, rollback snapshots, or policy package with any other estate unless I explicitly ask for a combined portfolio analysis.

Use https://tagtamer.vanroojen.com/. If a saved settings file exists, reopen `tagtamer.<estate-id>.saved-settings.json` first. Export or request Azure Resource Graph inventory as `tagtamer.<estate-id>.inventory.json`. Keep rollback as `tagtamer.<estate-id>.rollback.<YYYY-MM-DD>.json`. Name the final package `tagtamer.<estate-id>.policy-package.zip`.

When reporting back, include the estate id, cloud, scope, inventory file, saved settings file, rollback file, package file, dry-run summary, and any unresolved tag-model decisions.
```

## Handoff Checklist

- Estate id:
- Azure cloud: `AzureCloud` or `AzureUSGovernment`
- Tenant or tenant alias:
- Scope type: subscription, management group, resource group, or mixed inventory
- Subscription ids:
- Inventory file:
- Saved settings file:
- Mapping file:
- Rollback snapshot:
- Policy package:
- Dry-run summary:
- Open decisions:
- Deployment status:

## Safety Notes

- TagTamer does not sign into Azure or store customer inventory on a vanRoojen server.
- Imported inventory may include sensitive operational metadata such as resource IDs, names, subscription IDs, and tags.
- Rollback snapshots are operational records and should be handled like change-management evidence.
- Catch-all aliases such as `no=*` apply only to resources where the tag key exists; they do not create missing tags by themselves.
- Required tags should have defaults before apply/remediation packages are used.