@jaguilar87/gaia 5.0.0-rc.2

package/skills/gaia-verify/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: gaia-verify
+description: Use when the user wants to verify a Gaia installation -- "probemos", "verify", "test installation", "gaia-verify"
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Gaia Verify
+
+Verify that a Gaia installation works correctly across 4 modes. Each mode tests a different delivery surface. Use the mode that matches what was just changed or installed.
+
+## Decision Tree
+
+```
+"probemos" / "verify" / "test installation"
+├─ Just edited source code?       -> live
+├─ About to publish to npm?       -> dry-run
+├─ Just published @beta?          -> beta
+└─ Just published @latest?        -> release
+```
+
+If the user does not specify a mode, ask: "Which mode -- live, dry-run, beta, or release?"
+
+## Mode: live
+
+Tests the current symlinked installation. Source code is live -- no build step.
+
+**When:** After editing source files in `gaia-dev/`
+
+Commands: run `gaia-doctor` then `gaia-status` directly (already installed, no npx needed).
+
+**No temp directory.** No cleanup needed.
+
+## Mode: dry-run
+
+Tests the build pipeline -- does `npm pack` + local install produce a working installation?
+
+**When:** Before publishing to npm
+
+Step-by-step commands in `reference.md`. Core flow: `npm pack` in `gaia-dev` -> install `.tgz` in `/tmp/gaia-dry-run-{timestamp}` -> `npx gaia-doctor` + `npx gaia-status` -> clean up.
+
+## Mode: beta
+
+Tests the published `@beta` tag on the npm registry.
+
+**When:** After publishing a beta release via the pipeline
+
+Step-by-step commands in `reference.md`. Core flow: fresh `/tmp/gaia-beta-verify-{timestamp}` -> `npm install @jaguilar87/gaia@beta` -> `npx gaia-doctor` + `npx gaia-status` -> clean up.
+
+## Mode: release
+
+Tests the published `@latest` tag on the npm registry.
+
+**When:** After publishing a stable release via the pipeline
+
+Step-by-step commands in `reference.md`. Core flow: fresh `/tmp/gaia-release-verify-{timestamp}` -> `npm install @jaguilar87/gaia@latest` -> `npx gaia-doctor` + `npx gaia-status` -> clean up.
+
+## All Modes: Reporting
+
+Every mode ends with a structured result:
+
+```
+Mode:     <live | dry-run | beta | release>
+Version:  <version string installed, or "symlinked source" for live>
+Doctor:   PASS | FAIL
+Status:   <gaia-status output summary>
+Cleanup:  done | n/a (live)
+```
+
+If `gaia-doctor` fails, report the exact error and stop -- do not continue to `gaia-status`.
+
+## Anti-Patterns
+
+- **Skipping the mode question** -- each mode tests a different surface; running the wrong one gives false confidence.
+- **Skipping cleanup** -- `/tmp/gaia-{mode}-*` directories accumulate; always delete after reporting.
+- **Continuing after doctor failure** -- a failing doctor means the installation is broken; status output is meaningless.

package/skills/gaia-verify/reference.md

@@ -0,0 +1,80 @@
+# Gaia Verify Reference
+
+Exact commands for each mode. Copy and run -- no interpretation needed.
+
+## Mode: live
+
+```bash
+gaia-doctor
+gaia-status
+```
+
+No temp directory. No cleanup.
+
+## Mode: dry-run
+
+1. Go to the source repo (renamed to `gaia-dev` post-rename):
+   `cd /home/jorge/ws/me/gaia-dev`
+
+2. Pack the package (from the gaia source repo; path below uses the future rename but current dir is still `gaia-ops-dev`):
+   `npm pack`
+   Note the `.tgz` filename output (e.g., `jaguilar87-gaia-5.3.0.tgz`).
+
+3. Create a clean temp project (use actual timestamp):
+   `mkdir /tmp/gaia-dry-run-$(date +%Y%m%d%H%M%S)`
+
+4. Initialize:
+   `npm init -y` (run inside the temp dir)
+
+5. Install from tarball (use absolute path):
+   `npm install /home/jorge/ws/me/gaia-dev/jaguilar87-gaia-X.Y.Z.tgz`
+
+6. Verify:
+   `npx gaia-doctor`
+   `npx gaia-status`
+
+7. Clean up:
+   `rm -rf /tmp/gaia-dry-run-*`
+
+## Mode: beta
+
+1. Create a clean temp project (use actual timestamp):
+   `mkdir /tmp/gaia-beta-verify-$(date +%Y%m%d%H%M%S)`
+
+2. Initialize:
+   `npm init -y` (run inside the temp dir)
+
+3. Install from npm registry:
+   `npm install @jaguilar87/gaia@beta`
+
+4. Verify:
+   `npx gaia-doctor`
+   `npx gaia-status`
+
+5. Clean up:
+   `rm -rf /tmp/gaia-beta-verify-*`
+
+## Mode: release
+
+1. Create a clean temp project (use actual timestamp):
+   `mkdir /tmp/gaia-release-verify-$(date +%Y%m%d%H%M%S)`
+
+2. Initialize:
+   `npm init -y` (run inside the temp dir)
+
+3. Install from npm registry:
+   `npm install @jaguilar87/gaia@latest`
+
+4. Verify:
+   `npx gaia-doctor`
+   `npx gaia-status`
+
+5. Clean up:
+   `rm -rf /tmp/gaia-release-verify-*`
+
+## Notes
+
+- Run each command separately and verify exit code before proceeding (command-execution discipline).
+- For dry-run, `npm pack` must be run from `gaia-dev` -- the `.tgz` lands in the current working directory.
+- For beta/release, the install step requires network access to the npm registry. If it fails with `E404`, the version has not published yet -- wait and retry.
+- `npx gaia-doctor` exits non-zero on failure. If it fails, stop and report the error. Do not run `gaia-status`.

package/skills/git-conventions/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: git-conventions
+description: Use when creating a git commit or preparing changes for a pull request
+metadata:
+  user-invocable: false
+  type: reference
+---
+
+# Git Conventions
+
+## Commit Format
+
+| Element | Rule |
+|---------|------|
+| Format | `type(scope): short description` |
+| Types | feat, fix, refactor, docs, test, chore, ci, perf, style, build |
+| Scope | Optional, reflects module/area changed |
+| Subject | Max 72 chars, lowercase start, imperative mood, no period, no emoji |
+| Body | Optional, blank line after subject, 72 char line wrap |
+| Footers | `BREAKING CHANGE:`, `Refs:`, `Closes:`, `Fixes:`, `Implements:`, `See:` |
+
+## Examples
+
+```
+feat(helmrelease): add Phase 3.3 services
+fix(pg-non-prod): correct API key environment variable mappings
+refactor: simplify context provider logic
+chore(deps): update terraform to v1.6.0
+```
+
+## Git Path Flags
+
+`git -C <path>`, `git --git-dir=<path>`, and `git --work-tree=<path>` break
+the permission system. Allow/deny rules match command prefixes like
+`git commit:*` -- path flags inserted before the subcommand shift the prefix
+and bypass all rules silently. Run `cd` as a separate Bash call, then run git.
+
+## Push Defaults
+
+Push to the feature branch. Only push directly to `main` when explicitly
+instructed or when the work is already on main. Force-push (`--force`)
+requires explicit user instruction.
+
+## Hook Enforcement
+
+The `commit_validator.py` hook validates against `config/git_standards.json`.
+Format violations block the commit. Body line length triggers warnings only.

package/skills/gitops-patterns/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: gitops-patterns
+description: Use when creating, modifying, or reviewing Kubernetes manifests, HelmReleases, or Flux configuration
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# GitOps Patterns
+
+Reference conventions for Kubernetes, HelmRelease, and Flux. The codebase is the authority -- these patterns help you find and interpret what's already there.
+
+For YAML examples, troubleshooting, and resource limit defaults, read `reference.md` in this directory.
+
+## Discover the Project's GitOps Layout
+
+Before creating any manifest, understand how THIS project organizes its GitOps repo.
+
+1. **Find the repo root.** Check project-context for `gitops_repo_path`. If absent, look for a directory containing `clusters/`, `flux-system/`, or Kustomization files.
+2. **Read 2-3 existing HelmReleases.** How are values structured? What chart sources are used? What reconciliation intervals are set?
+3. **Check namespace organization.** Some projects use one directory per namespace; others group by service or environment. Follow what exists.
+4. **Follow the majority pattern.** If existing services use `kebab-case` names and `{service}-config` ConfigMaps, yours should too.
+
+## Repository Structure (Reference)
+
+Common layout -- defer to what the project actually uses.
+
+```
+{gitops_repo_path}/
+├── clusters/{cluster-name}/     # Flux entrypoint per cluster
+├── infrastructure/
+│   ├── base/                    # Shared: namespaces, sources
+│   └── overlays/{env}/          # Per-environment patches
+└── apps/
+    ├── base/{service}/          # Per-service Kustomize base
+    └── overlays/{env}/          # Per-environment patches
+```
+
+## Naming Conventions
+
+| Resource | Pattern | Example |
+|----------|---------|---------|
+| Namespace | `kebab-case` | `common`, `mobile-backend` |
+| Service / HelmRelease | `kebab-case` | `products-service` |
+| ConfigMap | `{service}-config` | `products-service-config` |
+| Secret | `{service}-secret` | `products-service-secret` |
+| Kustomization | `{scope}-{env}` | `apps-oci-dev` |
+
+## Image Versioning
+
+Flux ImagePolicy uses semver ranges (e.g., `>=1.0.0`) to auto-promote tags. Mutable tags like `latest`, `main`, or `dev` break this -- Flux cannot determine which is newer, so reconciliation either picks the wrong image or loops indefinitely. Always use semantic versioning: `v1.0.xxx`.
+
+## Key Rules
+
+1. **Git is the single source of truth** — `kubectl apply` directly bypasses reconciliation, creating drift that Flux will either revert (losing your change) or conflict with (breaking the next deploy)
+2. **Semver tags only** — mutable tags break image automation (see above)
+3. **Secrets via SealedSecrets** — plain secrets in Git are readable by anyone with repo access; SealedSecrets encrypt at rest and decrypt only in-cluster
+4. **Resource limits on every workload** — without limits, a single pod can starve the node; without requests, the scheduler cannot bin-pack efficiently
+5. **Verify cluster context first** — `kubectl config current-context` before any operation; applying to the wrong cluster is the most common and most damaging mistake
+6. **Post-push verification** — after pushing manifests, verify Flux reconciled successfully; a merged manifest that fails to apply is worse than no change at all. See `reference.md` for the exact command sequence

package/skills/gitops-patterns/reference.md

@@ -0,0 +1,183 @@
+# GitOps Patterns — YAML Reference
+
+Structural patterns for Kubernetes and Flux. Use placeholders — replace with values from project-context.
+
+For cloud-specific resource examples, discover patterns from the existing codebase using the `investigation` skill.
+
+---
+
+## HelmRelease
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: {service-name}
+  namespace: {namespace}
+spec:
+  interval: 5m
+  chart:
+    spec:
+      chart: {chart-name}
+      version: '>=1.0.0'
+      sourceRef:
+        kind: GitRepository
+        name: helm-charts
+        namespace: flux-system
+      interval: 1m
+  values:
+    image:
+      repository: {registry}/{service-name}
+      tag: v1.0.0
+    resources:
+      requests:
+        memory: "256Mi"
+        cpu: "100m"
+      limits:
+        memory: "512Mi"
+        cpu: "500m"
+```
+
+## Namespace
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {namespace}
+  labels:
+    name: {namespace}
+    environment: {env}
+```
+
+## ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {service-name}-config
+  namespace: {namespace}
+data:
+  KEY: "value"
+```
+
+## SealedSecret
+
+```yaml
+apiVersion: bitnami.com/v1alpha1
+kind: SealedSecret
+metadata:
+  name: {service-name}-secret
+  namespace: {namespace}
+spec:
+  encryptedData:
+    SECRET_KEY: AgB...  # Encrypted with kubeseal
+```
+
+## Kustomization
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: {scope}-{env}
+  namespace: flux-system
+spec:
+  interval: 1m
+  path: ./clusters/{cluster-name}
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+```
+
+## ImagePolicy
+
+```yaml
+apiVersion: image.toolkit.fluxcd.io/v1beta1
+kind: ImagePolicy
+metadata:
+  name: {service-name}
+spec:
+  imageRepositoryRef:
+    name: {service-name}
+  policy:
+    semver:
+      range: '>=1.0.0'
+```
+
+## Health Probes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: {port}
+  initialDelaySeconds: 30
+  periodSeconds: 10
+  timeoutSeconds: 5
+  failureThreshold: 3
+readinessProbe:
+  httpGet:
+    path: /ready
+    port: {port}
+  initialDelaySeconds: 5
+  periodSeconds: 5
+  timeoutSeconds: 3
+  failureThreshold: 3
+```
+
+## Troubleshooting
+
+| Issue | Check | Solution |
+|-------|-------|----------|
+| Pod not starting | `kubectl describe pod {name} -n {ns}` | Check events, resource limits, image pull |
+| HelmRelease failed | `flux get helmrelease {name} -n {ns}` | Check chart version, values syntax |
+| Image not found | `kubectl describe pod {name} -n {ns}` | Verify image exists in registry, check tag |
+| Service pending | `kubectl get svc -n {ns}` | Check cloud quotas, subnet/network config |
+| Flux not reconciling | `flux get kustomizations` | Check source sync, path exists |
+
+## Post-Push Verification
+
+After pushing manifests to Git (T3), verify Flux reconciled successfully. Run each command separately:
+
+```bash
+flux reconcile helmrelease {name} -n {namespace} --timeout=30s
+```
+
+```bash
+kubectl wait --for=condition=Ready helmrelease/{name} -n {namespace} --timeout=120s
+```
+
+```bash
+kubectl get helmrelease {name} -n {namespace} -o jsonpath='{.status.conditions[?(@.type=="Ready")]}'
+```
+
+## Debug Commands
+
+```bash
+flux get helmrelease {service-name} -n {namespace} --verbose
+kubectl logs -n {namespace} deployment/{service-name} --tail=100
+kubectl get events -n {namespace} --sort-by='.lastTimestamp'
+kubectl top pods -n {namespace}
+```
+
+## Resource Limits
+
+Always set both requests AND limits:
+
+| Size | CPU Req | CPU Lim | Mem Req | Mem Lim |
+|------|---------|---------|---------|---------|
+| Small | 100m | 500m | 256Mi | 512Mi |
+| Medium | 250m | 1000m | 512Mi | 1Gi |
+| Large | 500m | 2000m | 1Gi | 2Gi |
+
+## Secrets Management
+
+```
+Preference order:
+1. SealedSecrets (Bitnami) — encrypted in Git, decrypted in cluster
+2. External Secrets — from cloud secret store (Secret Manager, Vault)
+3. NEVER plain Kubernetes Secrets in Git
+```

package/skills/gmail-policy/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: gmail-policy
+description: Use when managing Gmail messages, labels, or email workflows via gws CLI or Gmail MCP tools
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Gmail Policy
+
+## Reading User Intent Before Acting
+
+The most common mistake is treating every email-related request as an execution command. Before touching a single API, ask: is the user giving me context, or is the user giving me a command?
+
+This is a reasoning step, not a checklist. Run it silently before every response.
+
+### The Four Questions
+
+1. **Context or command?** Is the user describing a situation, or directing an action?
+2. **If command -- explicit or ambiguous?** Explicit means the verb leaves no doubt (send, dile que sí y envíaselo). Ambiguous means the verb could be draft or send.
+3. **Reversible or sensitive?** A simple scheduling reply is reversible. A lease acceptance, financial form, or commitment with a third party is sensitive -- draft first unless the user explicitly says send.
+4. **Am I in a proactive triage context?** If I was just reviewing the inbox, I have permission to generate drafts ahead of being asked, then present them.
+
+### Intent Classification Table
+
+| Lo que dice el user | Intent real | Acción correcta |
+|---------------------|-------------|-----------------|
+| "necesito analizar un correo y enviar unos correos importantes" | Contexto -- está contándote el plan, no ejecutando | No hacer nada de envío; esperar el comando específico |
+| "chequea mis correos y ve si hay algo importante" | Review + iniciativa concedida | Leer inbox, triage, **generar drafts** para los que merezcan respuesta, presentar lista al user |
+| "dile que aceptamos y envíaselo" | Comando explícito de envío | Crear y enviar directamente (un solo ciclo T3, no draft→send) |
+| "mándale un correo a X diciéndole Y" | Ambiguo | Preguntar: ¿quiere draft para revisar o envío directo? |
+| "respóndele a Assetplan aceptando" | Ambiguo, tendencia a draft | Default a draft si el contenido involucra datos personales, decisiones comerciales, o formularios |
+| "dile que llego a las 5pm" | Comando simple, contenido reversible | Envío directo está bien sin pasar por draft |
+| "prepara una respuesta para X" | Draft explícito | Crear draft y reportar |
+
+### The Anti-Drift Rule
+
+There is no fixed pipeline where every send goes through draft→approve→send. That workflow exists as a safety net for sensitive cases, not as the default for every email. When the user says "envíaselo", they mean send -- one T3 approval, one action, done.
+
+The question is not "should I always draft first?" The question is: **what did the user actually ask for, and how reversible is this action?**
+
+If you're uncertain, ask once. Do not silently choose draft when the user said send.
+
+## Proactive Draft Generation (Triage Context)
+
+During a triage or inbox review session ("chequea mis correos", "ve si hay algo importante"), the user grants implicit permission for proactive drafts. You do not need to ask for approval before creating each one.
+
+Pattern:
+1. Read inbox, identify threads that clearly need a response
+2. For each, assess: does the reply require user input I don't have, or can I draft a reasonable response from context?
+3. If draftable -- draft it. Store the draft in Gmail. Note the draft ID.
+4. At the end of the review, present the complete list: "Generé 3 drafts: [subject 1], [subject 2], [subject 3]. ¿Quieres revisarlos?"
+
+The user reviews and approves individual drafts before sending. The generation step does not require one-by-one confirmation -- the presentation step does.
+
+Do not generate drafts proactively outside triage context. If the user opens a conversation about a single email, default to their explicit instruction.
+
+## Sending: When Draft and When Direct
+
+| Scenario | Default action |
+|----------|---------------|
+| User says "envíaselo" / "mándalo" / "dile que sí y envíaselo" | Send direct -- T3 approval for `send`, not for draft then send again |
+| User says "prepara una respuesta" / "redacta" | Draft |
+| Reply contains PII (RUT, cuenta bancaria, dirección, DOB) | Draft even if user said "mándale" -- confirm before send |
+| Reply is a business commitment (arrendamiento, contrato, formulario) | Draft unless user explicitly says send |
+| Simple logistics (hora, confirmación de asistencia, "llegaré tarde") | Direct send fine |
+| Ambiguous command + first time with this recipient | Ask once |
+
+When you do create a draft, verify it with `gws gmail users drafts list` and report the draft ID and snippet to the user. This closes the loop.
+
+## Multi-Source Data Completion
+
+Before asking the user for a datum (RUT, dirección, cuenta bancaria, etc.), check these sources in order:
+
+1. **Other Gmail threads** (priority 1) -- search for related threads. A user's RUT might appear in a Colmena thread. A property address might appear in a previous landlord thread. Connecting emails is the preferred path.
+2. **Local structured documents** -- `~/Documents/personal/**/data.json`, spreadsheets
+3. **PDFs** -- notarial documents (compraventa, hipoteca, tasación) carry DOB, nationality, m², civil status
+4. Only ask the user for data not found in any source
+
+When you find data in another thread, cite the source: "Tu RUT lo saqué de un correo de Colmena del 2024-03." This builds trust and shows the search was real.
+
+## PII Hygiene
+
+Any `.eml` or temporary file containing PII (RUT, cuenta bancaria, teléfono, DOB, dirección) must be deleted with `rm` after the draft is created. Verify deletion with Glob or `ls`. Report: "Archivo temporal eliminado."
+
+## Security Tier Classification
+
+| Operation | Tier | Notes |
+|-----------|------|-------|
+| `gws gmail users messages list` | T0 | Search/filter messages |
+| `gws gmail users messages get` | T0 | Read message content |
+| `gws gmail users labels list` | T0 | List available labels |
+| `gws gmail users labels get` | T0 | Read label details |
+| `gws gmail +search` | T0 | Macro search (syntactic sugar over list) |
+| `gws gmail users messages modify --addLabelIds` | T0 | Add any `_gaia/*` label (non-destructive) |
+| `gws gmail users messages modify --removeLabelIds` | T2 | Changes message visibility |
+| `gws gmail users messages modify` (action→waiting after send) | T2 | Auto-transition after user reply -- logged, no approval |
+| `gws gmail users drafts create` | T3 | Creates draft on user's behalf |
+| `gws gmail users drafts list` | T0 | Verify draft was created |
+| `gws gmail +reply --message-id --body` | T3 | Sends reply on user's behalf |
+| `gws gmail users messages send --params` | T3 | Sends/replies via raw RFC 2822 |
+| `gws gmail users labels create` | T3 | Creates new label |
+
+### Blocked Operations
+
+Permanently denied by the hook -- `gmail.modify` OAuth scope excludes delete at the API level.
+
+| Operation | Reason |
+|-----------|--------|
+| `gws gmail users messages delete` | Permanent, unrecoverable |
+| `gws gmail users messages trash` | Moves to trash (use `_gaia/trash` label instead) |
+| `gws gmail users messages purge` | Permanent purge |
+| `gws gmail users drafts delete` | Draft deletion |
+
+### Macro Prefix Handling
+
+`gws` CLI exposes convenience macros prefixed with `+` (e.g. `+reply`, `+send`, `+search`). The hook strips the leading `+` before the verb taxonomy lookup inside `detect_mutative_command()`, so each macro classifies like its base verb:
+
+- `gws gmail +reply` → token `reply` → match in MUTATIVE_VERBS → T3 block
+- `gws gmail +send` → token `send` → match in MUTATIVE_VERBS → T3 block
+- `gws gmail +search` → token `search` → match in READ_ONLY_VERBS → safe
+
+Fix applied 2026-04-17 in `hooks/modules/security/mutative_verbs.py` after a `+reply` invocation slipped through as "safe by elimination" during a Gmail session.
+
+## Sending Replies
+
+### When to use `+reply` vs `send --params`
+
+| Use case | Command | Pros | Cons |
+|----------|---------|------|------|
+| Simple plaintext reply | `gws gmail +reply --message-id <id> --body "<text>"` | Simple, handles threading headers automatically | Plaintext only, no HTML, no collapsed quote, no signature |
+| HTML reply with signature + collapsed quote | `gws gmail users messages send --params '{"userId":"me","threadId":"<tid>","raw":"<base64url>"}'` | Full control over MIME, looks native in Gmail | Must construct RFC 2822 manually and base64url-encode |
+
+Use `+reply` for quick operational replies where formatting does not matter. Use `send --params` when the recipient will see the mail in a mail client and visual quality matters.
+
+For the correct `gws gmail users drafts create` schema, RFC 2822 template, base64url encoding pipeline, and other technical patterns -- see `reference.md` in this skill directory.
+
+## Label Convention
+
+### Workflow Labels (Layer 0 -- `_gaia/*`)
+
+| Label | Purpose | Lifecycle |
+|-------|---------|-----------|
+| `_gaia/action` | I need to do something (respond, pay, read) | Clears when user acts → moves to `waiting` or removed |
+| `_gaia/waiting` | I already acted, waiting for the other party | Clears when other party responds → back to `action` or removed |
+| `_gaia/someday` | Interesting but no urgency (promos, articles, ideas) | Resurfaces in weekly review, user clears manually |
+| `_gaia/pending` | Staging area during mass triage | Empties during triage sessions |
+| `_gaia/trash` | Soft delete | Accumulates, user reviews |
+
+No `_gaia/*` label = processed/done. No extra label needed.
+
+### State Transitions
+
+```
+inbox ──→ action   (user or AI: I need to act)
+inbox ──→ waiting  (AI detects user already replied in thread)
+inbox ──→ someday  (user defers, no urgency)
+inbox ──→ trash    (not wanted)
+inbox ──→ pending  (mass triage staging)
+
+action  ──→ waiting  (user replied/acted → auto T1 transition)
+action  ──→ done     (handled, no follow-up → remove label)
+action  ──→ someday  (user defers)
+
+waiting ──→ action  (other party replied → needs user attention)
+waiting ──→ done    (resolved → remove label)
+
+someday ──→ action  (user decides to act)
+someday ──→ trash   (not worth it)
+someday ──→ done    (reviewed, no action needed → remove label)
+
+pending ──→ {action, waiting, someday, trash, done}  (triage output)
+```
+
+### Calendar Rule
+
+When an email contains a specific date/time deadline (bill due date, event, appointment): create a calendar event AND label the email `_gaia/action`. The calendar is the time-trigger; the label is the state-tracker.
+
+### Content Labels (Layer 1)
+
+| Category | Labels |
+|----------|--------|
+| Finance | `Finance/Bank`, `Finance/Transfers`, `Finance/Insurance` |
+| Jobs | `Jobs/Alerts`, `Jobs/Academic` |
+| Shopping | `Shopping/Promos`, `Shopping/Orders` |
+| Music | `Music/Nucleo`, `Music/DJ` |
+| Social | `Social/LinkedIn`, `Social/Facebook` |
+| Services | `Services/Subscriptions`, `Services/Utilities` |
+| Tech | `Tech/Programming`, `Tech/SalesForce` |
+| Personal | `Personal/Notes`, `Personal/Travel`, `Personal/Downloads` |
+| Legacy | `_gaia/legacy` -- retired: Buzz!!, Isercon, WaReS, +1, multi-forward, GDrive, PokerStar |
+
+## OAuth Scope
+
+Use `gmail.modify` scope (read + label + move, no delete). Full access scope (`https://mail.google.com/`) is blocked -- it includes delete permissions that bypass both hook and label controls.
+
+## Related Skills
+
+- `gmail-triage` -- interactive triage workflow
+- `gws-setup` -- CLI installation and authentication