@event4u/agent-config 9.9.0 → 9.11.0

package/agents/templates/.ai-video.xml.example

@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  agents/.ai-video.xml.example
+  ============================
+
+  Operator-facing provider configuration for the /video:* command cluster.
+
+  Copy this file to `agents/.ai-video.xml` and fill in the API keys for the
+  providers you actually use. The real file is gitignored and MUST NEVER be
+  committed.
+
+  Loader: scripts/media/lib/load-config.sh
+  Redaction: scripts/media/lib/redact.sh
+  Docs: agents/reference/ai-video/README.md
+-->
+<ai-video version="1">
+
+  <!--
+    Defaults: pick which provider a /video:* run uses when the command
+    does not pass the image-provider / video-provider flags. Must match
+    a provider id="..." declared below.
+
+    Each provider carries a <lifecycle> tag — experimental | stable |
+    deprecated | community — per docs/contracts/provider-lifecycle.md.
+    Day-one shipped tiers are conservative: every adapter is
+    `experimental` until a maintainer captures a real-API smoke trace.
+    The agent refuses to *default* to a non-stable provider silently;
+    it surfaces the tier and asks before running.
+  -->
+  <default-image-provider>openai-images</default-image-provider>
+  <default-video-provider>gemini-veo</default-video-provider>
+
+  <!-- ============================================================ -->
+  <!-- Image providers                                              -->
+  <!-- ============================================================ -->
+
+  <provider id="openai-images" kind="image">
+    <lifecycle>stable</lifecycle>
+    <api-key>sk-REPLACE-ME</api-key>
+    <endpoint>https://api.openai.com/v1</endpoint>
+    <default-model>gpt-image-1</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <quality>high</quality>
+      <best-of-n>4</best-of-n>
+    </tuning>
+  </provider>
+
+  <!-- ============================================================ -->
+  <!-- Video providers                                              -->
+  <!-- ============================================================ -->
+
+  <provider id="higgsfield" kind="image+video">
+    <lifecycle>stable</lifecycle>
+    <api-key>hf-REPLACE-ME</api-key>
+    <endpoint>https://api.higgsfield.ai/v1</endpoint>
+    <default-model>higgsfield-soul</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <preset>cinematic</preset>
+      <max-duration>5</max-duration>
+      <best-of-n>2</best-of-n>
+    </tuning>
+  </provider>
+
+  <provider id="gemini-veo" kind="video">
+    <lifecycle>stable</lifecycle>
+    <api-key>AIza-REPLACE-ME</api-key>
+    <endpoint>https://generativelanguage.googleapis.com/v1beta</endpoint>
+    <default-model>veo-3.0-generate-001</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <fps>24</fps>
+      <max-duration>8</max-duration>
+      <audio-native>true</audio-native>
+    </tuning>
+  </provider>
+
+  <provider id="kling" kind="video">
+    <lifecycle>stable</lifecycle>
+    <access-key>kling-access-REPLACE-ME</access-key>
+    <secret-key>kling-secret-REPLACE-ME</secret-key>
+    <endpoint>https://api.klingai.com/v1</endpoint>
+    <default-model>kling-v2-master</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <fps>30</fps>
+      <max-duration>10</max-duration>
+      <audio-native>false</audio-native>
+    </tuning>
+  </provider>
+
+  <provider id="sora" kind="video">
+    <lifecycle>stable</lifecycle>
+    <api-key>sora-REPLACE-ME</api-key>
+    <endpoint>https://api.openai.com/v1</endpoint>
+    <default-model>sora-2</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <fps>30</fps>
+      <max-duration>20</max-duration>
+      <audio-native>true</audio-native>
+    </tuning>
+  </provider>
+
+  <!-- ============================================================ -->
+  <!-- Multiplexer providers — one adapter, many models             -->
+  <!-- Model selection: top-level `model_id` stdin key overrides    -->
+  <!-- <default-model>. Per-model capabilities:                     -->
+  <!-- scripts/ai-video/lib/model-capabilities/<id>.json            -->
+  <!-- Kill-switch: <enabled>false</enabled> refuses every network  -->
+  <!-- subcommand without editing procedures that name the provider.-->
+  <!-- ============================================================ -->
+
+  <provider id="fal" kind="video">
+    <lifecycle>stable</lifecycle>
+    <enabled>true</enabled>
+    <api-key>fal-REPLACE-ME</api-key>
+    <endpoint>https://queue.fal.run</endpoint>
+    <default-model>fal-ai/ltx-2/text-to-video</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <max-duration>10</max-duration>
+      <audio-native>false</audio-native>
+    </tuning>
+  </provider>
+
+  <provider id="replicate" kind="video">
+    <lifecycle>stable</lifecycle>
+    <enabled>true</enabled>
+    <api-key>r8_REPLACE-ME</api-key>
+    <endpoint>https://api.replicate.com/v1</endpoint>
+    <default-model>kwaivgi/kling-v2.1-master</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <max-duration>10</max-duration>
+      <audio-native>false</audio-native>
+    </tuning>
+  </provider>
+
+  <!--
+    Local ComfyUI (ADR-060 — container-primary sandbox). No api-key:
+    the adapter talks to YOUR ComfyUI. A loopback endpoint is assumed
+    to be the shipped container posture (read-only image, cap-drop ALL,
+    network-none at generation time — run line in the adapter header).
+    A NON-loopback endpoint is the remote escape hatch: isolation is
+    the operator's responsibility and the block must carry
+    <unsandboxed>accepted</unsandboxed> or the adapter refuses (exit 6).
+    Models: wan22-ti2v-5b (default, Apache-2.0) | ltx-2 (audio-sync).
+    Shipped workflow templates only — operator workflow JSONs are
+    rejected by design. macOS: no CUDA — container path is
+    reference-only; use the remote escape hatch.
+  -->
+  <provider id="comfyui" kind="video">
+    <lifecycle>experimental</lifecycle>
+    <enabled>true</enabled>
+    <endpoint>http://127.0.0.1:8188</endpoint>
+    <default-model>wan22-ti2v-5b</default-model>
+    <dry-run>true</dry-run>
+    <tuning>
+      <aspect>16:9</aspect>
+      <max-duration>5</max-duration>
+      <audio-native>false</audio-native>
+    </tuning>
+  </provider>
+
+  <!-- ============================================================ -->
+  <!-- Audio adapters (music-video orchestration)                   -->
+  <!-- Contract: scripts/ai-video/lib/audio-adapter-contract.md     -->
+  <!-- local-cli adapters wrap an OPERATOR-installed tool (pip) —   -->
+  <!-- no api-key element needed; <enabled>false</enabled> opts a   -->
+  <!-- configured-but-unwanted adapter out (otherwise a missing CLI -->
+  <!-- is a loud config failure, never a silent probe fallback).    -->
+  <!-- ============================================================ -->
+
+  <provider id="allin1" kind="audio-analysis">
+    <lifecycle>experimental</lifecycle>
+    <enabled>true</enabled>
+    <dry-run>true</dry-run>
+  </provider>
+
+  <provider id="whisperx" kind="lyrics">
+    <lifecycle>experimental</lifecycle>
+    <enabled>true</enabled>
+    <dry-run>true</dry-run>
+  </provider>
+
+  <!-- ============================================================ -->
+  <!-- Lip-sync post-process (v2 contract, kind="lipsync")          -->
+  <!-- Sparse budget: lib/model-capabilities/syncso.json            -->
+  <!-- ============================================================ -->
+
+  <!--
+    Local (MIT) lip-sync — offline alternative to syncso. Wraps an
+    OPERATOR-installed MuseTalk (github.com/TMElyralab/MuseTalk); the
+    wrapped entry point is configurable via the MUSETALK_CMD env var.
+    No api-key. Same sparse lipsync_budget discipline as syncso
+    (lib/model-capabilities/musetalk.json) — local renders are free but
+    the quality argument for sparseness is unchanged.
+  -->
+  <provider id="musetalk" kind="lipsync">
+    <lifecycle>experimental</lifecycle>
+    <enabled>true</enabled>
+    <dry-run>true</dry-run>
+  </provider>
+
+  <provider id="syncso" kind="lipsync">
+    <lifecycle>experimental</lifecycle>
+    <enabled>true</enabled>
+    <api-key>sk-REPLACE-ME</api-key>
+    <endpoint>https://api.sync.so</endpoint>
+    <default-model>lipsync-2</default-model>
+    <dry-run>true</dry-run>
+  </provider>
+
+  <!-- ============================================================ -->
+  <!-- Extra slot — future providers without schema bump            -->
+  <!-- Use kind="image" | "video" | "image+video" | "audio-analysis"-->
+  <!-- | "lyrics" | "lipsync".                                      -->
+  <!-- ============================================================ -->
+
+  <extra>
+    <!--
+    <provider id="my-future-backend" kind="video">
+      <lifecycle>experimental</lifecycle>
+      <api-key>REPLACE-ME</api-key>
+      <endpoint>https://example.invalid/v1</endpoint>
+      <default-model>example-1</default-model>
+      <dry-run>true</dry-run>
+      <tuning>
+        <aspect>16:9</aspect>
+        <fps>24</fps>
+        <max-duration>6</max-duration>
+        <audio-native>false</audio-native>
+      </tuning>
+    </provider>
+    -->
+  </extra>
+
+</ai-video>

package/dist/agent-src/commands/agent-status.md

@@ -57,9 +57,9 @@ the last record from `agents/cost-tracking/sessions.jsonl`. If the file
 does not exist (tracker never run for this project), skip this step and
 note `cost ledger: not initialised` in the dashboard.
 
-Extract from latest record:
+Extract from the latest record:
 
-- `total_usd` — dollars spent in current session
+- `total_usd` — dollars spent in the current session
 - `by_model[]` — per-tier (haiku / sonnet / opus) input / output / cache split
 - `budget.tier` — `under` / `50` / `75` / `90` / `100` (from `node scripts/cost/budget.mjs check`)
 
@@ -68,19 +68,20 @@ implementation: [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs).
 
 ### 3b. Read telegraph delta + per-conversation cost lens
 
-Run two read-only Python helpers (stdlib-only, no-op safe if JSONL missing):
+Run two read-only Python helpers (both stdlib-only, both no-op safe if the
+JSONL is missing):
 
 - `./scripts-run src/scripts/telegraph_stats --format json` — per-session +
-  per-conversation + lifetime telegraph delta. Honors suspended
-  multiplier (see [`docs/contracts/telegraph-telemetry.md`](../docs/contracts/telegraph-telemetry.md)) — delta reads `0` while suspended; display version + ACTIVE/SUSPENDED state regardless.
+  per-conversation + lifetime telegraph delta. Honors the suspended
+  multiplier (see [`docs/contracts/telegraph-telemetry.md`](../docs/contracts/telegraph-telemetry.md)) — delta reads `0` while suspended; display the version + ACTIVE/SUSPENDED state regardless.
 - `./scripts-run src/scripts/cost_by_conversation --format json` — per-conversation
-  total cost + model breakdown for current conversation, sourced
-  from same `agents/cost-tracking/sessions.jsonl` ledger.
+  total cost + model breakdown for the current conversation, sourced
+  from the same `agents/cost-tracking/sessions.jsonl` ledger.
 
-Surface in dashboard as one line:
+Surface in the dashboard as one line:
 `[telegraph: {lifetime.delta_tokens:+,} tok lifetime · {current_conv.delta_tokens:+,} this conv · multiplier v{multiplier_version} {ACTIVE|SUSPENDED}] · [conv cost: ${current_conv.total_cost_usd:.4f}]`.
 
-If both JSONLs missing or empty, omit line silently.
+If both JSONLs are missing or empty, omit the line silently.
 
 ### 4. Calculate freshness thresholds
 
@@ -113,7 +114,7 @@ Use Markdown tables and headings — NOT ASCII box art (breaks in non-monospace
 
 **💵 Session cost (measured)**
 
-If ledger exists, render:
+If the ledger exists, render:
 
 | | |
 |---|---|
@@ -122,7 +123,7 @@ If ledger exists, render:
 | 🎯 Budget tier | {emoji} {tier} ({utilization_pct}% of cap) |
 
 Tier-emoji map: `under` / `50` → ✅ · `75` → ⚠️ · `90` → ⚠️⚠️ · `100` → ❌.
-If ledger does not exist, render `Session cost: not initialised — run \`task cost:track\` to start measuring`.
+If the ledger does not exist, render `Session cost: not initialised — run \`task cost:track\` to start measuring`.
 
 **⚡ Freshness**
 

package/dist/agent-src/commands/agents/user/accept.md

@@ -7,7 +7,7 @@ visibility: internal
 cluster: agents
 sub: user
 skills: [agents]
-description: Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and drops the applied observations from the buffer.
+description: Apply a buffered observation to .agent-user.md or the global profile.md after explicit user confirmation; bumps last_updated and drops the applied observations from the buffer.
 argument-hint: "[field]"
 suggestion:
   eligible: false
@@ -20,9 +20,16 @@ packs:
 
 # /agents user accept
 
-Apply a buffered observation from
-[`.agent-user.observations.jsonl`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
-to `.agent-user.md` after explicit confirmation.
+Apply a buffered observation from either
+[the project-local or the global observation buffer](../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
+to the matching profile file — `.agent-user.md` for a project-local
+observation, the global `~/.event4u/agent-config/user/profile.md` for a
+global one (ADR-138, road-to-global-user-memory Phase 2) — after
+explicit confirmation.
+
+This is the **only** step in the learning channel that writes a profile
+file. Everything upstream (the miner, the buffers, `/agents user review`)
+only ever proposes.
 
 Use when:
 
@@ -40,34 +47,77 @@ ls .agent-user.md 2>/dev/null
 ls .agent-user.observations.jsonl 2>/dev/null
 ```
 
-Either missing → print "Run `/agents user init` and accumulate
-observations first." and stop.
+Resolve the global buffer/profile paths via
+`user_global_observations.resolveGlobalObservationsPath()` /
+`agent_user_profile.resolveGlobalProfilePath()`.
+
+Both the project-local file/buffer AND the global profile/buffer
+missing → print "Run `/agents user init` and accumulate observations
+first." and stop. Otherwise proceed with whichever layer(s) have a
+buffered observation.
 
-### 2. Resolve target field
+### 2. Resolve target field + layer
 
-| Invocation | Resolved field |
+| Invocation | Resolved field + layer |
 |---|---|
-| Handed off from `/agents user review` option 1 | The most-frequent field |
-| `/agents user accept <field>` | `<field>` (must match the schema enum) |
-| `/agents user accept` with no arg | Print the field list, ask which |
+| Handed off from `/agents user review` option 1 | The most-frequent field, with the layer `review` reported it under |
+| Handed off from `/agents user review` option 4 (a promotion candidate) | The candidate's `suggest` text, layer `global` — see § 2b below, skip straight to step 4 with the promotion framing |
+| `/agents user accept <field>` | `<field>` (must match the schema enum); if both layers have an observation for it, ask which layer |
+| `/agents user accept` with no arg | Print the field list (both layers), ask which |
 
 Invalid field → print the schema enum and stop.
 
-### 3. Compute proposed change
+### 2b. Promotion candidates need a `promotion_reason` (road-to-global-user-memory Phase 3)
+
+A candidate handed off from review option 4 has `seen_count ≥ 3` and a
+`seen_in[]` project list — human-confirmed recurrence across that many
+DIFFERENT projects (per
+[`findPromotionCandidates`](../../../../../src/scripts/_lib/user_global_observations.ts)).
+Crossing that threshold is candidacy only; it never auto-promotes
+(mirroring ADR-121's rule that a knowledge card has no auto-`shareable`
+path). Before step 4's confirmation, collect one additional line from the
+user:
+
+```
+This observation recurred in {seen_count} projects: {seen_in joined by ", "}.
+
+Why should this generalise to your global profile?
+> {free-text promotion_reason — required, no default}
+```
 
-For the resolved field:
+An empty answer is not accepted — re-ask once, then fall back to
+"Cancel" if the user still declines to give a reason. The
+`promotion_reason` is shown in step 4's confirmation block (below) but is
+**never written to `profile.md`** — see § 3 write below; it exists to make
+the human's judgment call visible in this transcript, not to persist
+alongside the fact.
 
-1. Read every matching observation from the buffer.
-2. Pick the **latest** `suggest` value (most recent `ts` wins).
-3. Read the current value from `.agent-user.md`.
+### 3. Compute proposed change
+
+For the resolved field + layer — or, for a promotion candidate (§ 2b),
+the single matched buffer entry:
+
+1. Read every matching observation from that layer's buffer only —
+   `.agent-user.observations.jsonl` for `project`,
+   `user_global_observations.readGlobalObservations()` for `global`.
+2. Pick the **latest** `suggest` value (most recent `ts` wins). For a
+   promotion candidate, the proposed value is
+   [`promotionValueFor(candidate)`](../../../../../src/scripts/_lib/user_global_observations.ts) —
+   the fact text ONLY, never the `context` or `seen_in` metadata attached
+   to it.
+3. Read the current value from that layer's profile file
+   (`.agent-user.md` or the global `profile.md`) — NOT the merged
+   effective value, so the confirmation shows exactly what this layer
+   will change.
 4. If they match, print "No change — current value already matches
    the latest observation." and skip to step 6.
 
 ### 4. Confirm
 
 ```
-Apply this change to .agent-user.md?
+Apply this change to {.agent-user.md | the global profile}?
 
+  layer   : {project | global}
   field   : {field}
   current : "{current_value}"
   proposed: "{proposed_value}"
@@ -76,7 +126,15 @@ Apply this change to .agent-user.md?
 
 > 1. Apply
 > 2. Skip — keep current value, drop these observations from the buffer
-> 3. Cancel — leave .agent-user.md and buffer untouched
+> 3. Cancel — leave the profile and buffer untouched
+```
+
+For a promotion candidate, append two lines above `> 1. Apply` instead of
+`source`/`evidence`:
+
+```
+  seen in : {seen_count} projects ({seen_in joined by ", "})
+  reason  : "{promotion_reason from § 2b}"
 ```
 
 One question per turn. Wait for the user's number.
@@ -85,24 +143,40 @@ One question per turn. Wait for the user's number.
 
 On `1. Apply`:
 
-1. Rewrite the targeted field in `.agent-user.md` frontmatter.
-   Preserve every other field byte-for-byte (use a YAML round-trip
-   loader that keeps formatting).
-2. Bump `last_updated` to today (ISO `YYYY-MM-DD`).
-3. Validate the result: schema present, ≤100 lines, privacy floor
-   clean. Any violation → roll back and print the error.
-4. Drop **all** applied observations for that field from the buffer
-   (rewrite the JSONL minus matching lines).
-
-On `2. Skip`: leave `.agent-user.md` untouched but still drop the
-observations for that field from the buffer.
+- **`project` layer:** rewrite the targeted field in `.agent-user.md`
+  frontmatter, preserving every other field (a YAML round-trip loader
+  that keeps formatting), bump `last_updated` to today (ISO
+  `YYYY-MM-DD`), validate ≤100 lines + privacy floor clean — any
+  violation rolls back and prints the error.
+- **`global` layer:** call
+  [`applyObservationToGlobalProfile(field, value, { today })`](../../../../src/scripts/_lib/agent_user_profile.ts) —
+  it round-trips the existing `profile.md` (or starts from empty),
+  sets the field, bumps `last_updated`, and throws (never partially
+  writes) if the result would exceed the global layer's own 100-line
+  cap. A thrown error is the roll-back signal — print it and stop. For a
+  promotion candidate, `value` is `promotionValueFor(candidate)` — the
+  `promotion_reason` collected in § 2b is shown in step 4's confirmation
+  only; it is **never** passed to `applyObservationToGlobalProfile` and
+  never appears in `profile.md`, alongside `context`/`seen_in`, which are
+  likewise never written. This is the only generalisation path, and it
+  leaves the durable profile with zero project references (see
+  [`agent-user-schema.md § Project attribution`](../../../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3)).
+
+Either layer: drop **all** applied observations for that field from
+**that layer's own buffer only** (rewrite the JSONL minus matching
+lines) — never touch the other layer's buffer. For a promoted candidate,
+this drops only the ONE matched buffer entry (identified in § 2b), not
+every `notes`-field entry in the buffer.
+
+On `2. Skip`: leave the profile untouched but still drop the
+observations for that field from that layer's buffer.
 
 On `3. Cancel`: stop without any write.
 
 ### 6. Confirm
 
 ```
-✅  .agent-user.md updated ({field}: "{old}" → "{new}", last_updated: YYYY-MM-DD).
+✅  {layer} profile updated ({field}: "{old}" → "{new}", last_updated: YYYY-MM-DD).
    Buffer: {n} observations removed, {m} remaining.
 ```
 
@@ -115,11 +189,22 @@ Do NOT commit. Do NOT auto-chain to a second field.
 - Never write without explicit confirmation in step 4.
 - Never bypass the privacy-floor scan, even if the buffer writer
   already redacted.
+- Never write to the layer the observation did NOT come from — an
+  observation buffered as `global` writes `profile.md`, never
+  `.agent-user.md`, and vice versa.
+- Never accept a promotion candidate without a non-empty
+  `promotion_reason` (§ 2b) — a `seen_count ≥ 3` tally is candidacy, not
+  authorization.
+- Never write `context` or `seen_in` to `profile.md` — a promotion writes
+  `promotionValueFor(candidate)`, the fact text only.
 - Mirror the user's language for prompts per
   [`language-and-tone`](../../../../dist/agent-src/rules/language-and-tone.md).
 
 ## See also
 
 - Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
+- Project attribution + promotion: [`agent-user-schema § Project attribution`](../../../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3).
+- Global write primitive: [`agent_user_profile.applyObservationToGlobalProfile`](../../../../src/scripts/_lib/agent_user_profile.ts).
+- Promotion primitives: [`findPromotionCandidates`, `promotionValueFor`](../../../../../src/scripts/_lib/user_global_observations.ts).
 - Parent: [`/agents user`](../user.md).
 - Sibling: [`/agents user review`](review.md), [`/agents user update`](update.md).

package/dist/agent-src/commands/agents/user/delete.md

@@ -0,0 +1,147 @@
+---
+model_tier: medium
+name: agents-user-delete
+pack: meta
+tier: 2
+visibility: internal
+cluster: agents
+sub: user
+skills: [agents]
+description: Delete one buffered global observation, purge every observation attributed to a project, or revoke a field from the global profile.md — each writes an append-only tombstone before deleting.
+argument-hint: "[observation <id> | project <path> | profile-field <field>]"
+suggestion:
+  eligible: false
+  rationale: "Mutates the global observation buffer or profile.md — only run from /agents user review, /agents user show --audit, or explicit user invocation."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /agents user delete
+
+Delete something the learning channel wrote to the **global** layer —
+road-to-global-user-memory Phase 4, the delete counterpart of
+[`/agents user accept`](accept.md). Every deletion writes an
+append-only tombstone to the revocation ledger BEFORE the underlying
+file is rewritten without it — see
+[`agent-user-schema § Delete, revoke, and audit`](../../../../../docs/contracts/agent-user-schema.md#delete-revoke-and-audit-road-to-global-user-memory-phase-4).
+
+Three targets, one per invocation:
+
+| Target | Removes | Backing function |
+|---|---|---|
+| `observation <id>` | ONE buffered line from `observations.jsonl` | [`deleteGlobalObservation`](../../../../../src/scripts/_lib/user_global_observations.ts) |
+| `project <path>` | EVERY observation attributed (`context.project_path`) to that project | [`purgeProjectContext`](../../../../../src/scripts/_lib/user_global_observations.ts) |
+| `profile-field <field>` | A field's value from the global `profile.md` | [`revokeGlobalProfileField`](../../../../../src/scripts/_lib/agent_user_profile.ts) |
+
+Use when:
+
+- [`/agents user show --audit`](show.md) or
+  [`/agents user review`](review.md) surfaced something the user wants
+  gone.
+- A project was deleted and its buffered facts should not linger
+  forever (`project <path>`).
+- A promoted or accepted profile field turned out to be wrong
+  (`profile-field <field>`).
+
+Never runs autonomously — always asks before writing, exactly like
+`accept`.
+
+## Steps
+
+### 1. Resolve the target
+
+| Invocation | Target |
+|---|---|
+| `/agents user delete observation <id>` | The buffered observation whose `observationId` equals `<id>` (shown by `/agents user show --audit` or `/agents user review`) |
+| `/agents user delete project <path>` | Every observation whose `context.project_path` equals `<path>` |
+| `/agents user delete profile-field <field>` | `<field>` in the global `profile.md` (must match the schema enum) |
+| No argument | Print the target-kind table above and ask which; then ask for the id/path/field |
+
+Invalid `<field>` → print the schema enum and stop. No observation
+matches `<id>` → print "No buffered observation with that id." and
+stop (no tombstone is written for a no-op — see the backing functions'
+`deleted: false` / `purgedCount: 0` contract).
+
+### 2. Confirm
+
+```
+Delete this from the global user-memory layer?
+
+  target : {observation <id> | project <path> | profile-field <field>}
+  current: {for profile-field — the current value; for observation/project — the suggest text(s) that will be removed}
+
+> 1. Delete — write a tombstone, then remove
+> 2. Cancel — leave everything untouched
+```
+
+For `project <path>`, list every matched observation's `suggest` text
+before asking, so the user confirms the actual scope, not just a count.
+
+One question per turn. Wait for the user's number.
+
+### 3. Ask for a reason
+
+```
+Why is this being deleted? (one line, becomes the tombstone's `reason`)
+> {free-text reason}
+```
+
+An empty answer is not accepted — re-ask once, then default to `"no
+reason given"` if the user still declines (mirrors
+[`user_global_revocations.appendTombstone`](../../../../../src/scripts/_lib/user_global_revocations.ts)'s
+own fallback, so a user who truly has nothing to say is never blocked).
+
+### 4. Write
+
+On `1. Delete`, call the matching function with today's date and the
+step-3 reason:
+
+- `observation <id>` →
+  [`deleteGlobalObservation(id, reason, { today })`](../../../../../src/scripts/_lib/user_global_observations.ts).
+- `project <path>` →
+  [`purgeProjectContext(path, reason, { today })`](../../../../../src/scripts/_lib/user_global_observations.ts).
+- `profile-field <field>` →
+  [`revokeGlobalProfileField(field, reason, { today })`](../../../../../src/scripts/_lib/agent_user_profile.ts).
+
+Each function writes its tombstone(s) BEFORE the buffer/profile
+rewrite — never call `fs`/the file directly from this command; always
+go through the function so the tombstone-before-delete order holds.
+
+On `2. Cancel`: stop without any write, without any tombstone.
+
+### 5. Confirm
+
+```
+✅  Deleted ({target}). Tombstone recorded: {entity_id}, {revoked_at}.
+```
+
+For `project <path>`, report the count: `✅  Purged {n} observation(s) from {path}. {n} tombstone(s) recorded.`
+
+Do NOT commit. Do NOT auto-chain to a second deletion.
+
+## Rules
+
+- One target per invocation. Run the command again for the next
+  deletion.
+- Never delete without explicit confirmation in step 2 and a reason
+  from step 3.
+- Never write to a file directly — every deletion goes through
+  `deleteGlobalObservation`, `purgeProjectContext`, or
+  `revokeGlobalProfileField` so the tombstone always precedes the
+  delete.
+- Never touch project-local `.agent-user.md` or its buffer from this
+  command — this leaf covers the global layer only. A project-local
+  fact is deleted by editing `.agent-user.md` directly (it never left
+  the project) or via [`/agents user review`](review.md)'s existing
+  "clear a buffer" option.
+- Mirror the user's language for prompts per
+  [`language-and-tone`](../../../../dist/agent-src/rules/language-and-tone.md).
+
+## See also
+
+- Schema: [`agent-user-schema § Delete, revoke, and audit`](../../../../../docs/contracts/agent-user-schema.md#delete-revoke-and-audit-road-to-global-user-memory-phase-4) — the write→delete mapping and the ADR-121 reuse this command exposes.
+- Audit source: [`/agents user show --audit`](show.md) — the read surface that surfaces what there is to delete.
+- Parent: [`/agents user`](../user.md).
+- Sibling: [`/agents user review`](review.md), [`/agents user accept`](accept.md) — the write side this command undoes.