@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/commands/context-create.md

@@ -3,6 +3,10 @@ name: context-create
 skills: [agent-docs-writing]
 description: Analyze a codebase area and create a structured context document
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "document this part of the codebase, create a context doc for X"
+  trigger_context: "working in a module without an agents/contexts/ doc"
 ---
 
 # context-create

package/.agent-src/commands/context-refactor.md

@@ -3,6 +3,10 @@ name: context-refactor
 skills: [agent-docs-writing]
 description: Analyze, update, and extend an existing context document
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "update the context doc, refresh this context document"
+  trigger_context: "existing agents/contexts/*.md referenced in the prompt"
 ---
 
 # context-refactor

package/.agent-src/commands/copilot-agents-init.md

@@ -3,6 +3,9 @@ name: copilot-agents-init
 description: Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers.
 skills: [copilot-config, copilot-agents-optimization, agent-docs-writing]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Project init — only deliberately during onboarding."
 ---
 
 # /copilot-agents-init

package/.agent-src/commands/copilot-agents-optimize.md

@@ -3,6 +3,9 @@ name: copilot-agents-optimize
 description: Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience.
 skills: [copilot-agents-optimization, copilot-config, agent-docs-writing]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Maintenance refactor; only when the maintainer chooses to run it."
 ---
 
 # /copilot-agents-optimize

package/.agent-src/commands/create-pr-description.md

@@ -3,6 +3,10 @@ name: create-pr-description
 skills: [git-workflow]
 description: Generate a PR description as a copyable markdown block — used standalone or by create-pr
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "write a PR description, draft the PR text"
+  trigger_context: "PR exists or branch ready for review without description"
 ---
 
 # create-pr-description

package/.agent-src/commands/create-pr.md

@@ -3,6 +3,10 @@ name: create-pr
 skills: [git-workflow]
 description: Create a GitHub PR with structured description from Jira ticket and code changes
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "open a PR, create a pull request, make a PR for this branch"
+  trigger_context: "branch is ahead of base and not yet on a PR"
 ---
 
 # create-pr

package/.agent-src/commands/do-and-judge.md

@@ -3,6 +3,9 @@ name: do-and-judge
 skills: [subagent-orchestration, verify-before-complete]
 description: Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Subagent orchestration — overlaps /work and judge skills; keep explicit."
 ---
 
 # do-and-judge
@@ -59,7 +62,7 @@ same failure class on nearby paths during this session, that is a
 pattern worth recording. Drop a signal:
 
 ```bash
-python3 scripts/memory_signal.py \
+./agent-config memory:signal \
     --type historical-patterns \
     --path "<primary path under review>" \
     --body "<failure class → fix guidance, one sentence>" \

package/.agent-src/commands/do-in-steps.md

@@ -3,6 +3,9 @@ name: do-in-steps
 skills: [subagent-orchestration, verify-before-complete]
 description: Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Subagent orchestration — overlaps /work and /roadmap-execute; keep explicit."
 ---
 
 # do-in-steps

package/.agent-src/commands/e2e-heal.md

@@ -3,6 +3,10 @@ name: e2e-heal
 skills: [playwright-testing]
 description: Find, debug, and fix failing Playwright E2E tests
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix the failing E2E tests, playwright tests are red"
+  trigger_context: "failing test output from tests/e2e/"
 ---
 
 # e2e-heal

package/.agent-src/commands/e2e-plan.md

@@ -3,6 +3,10 @@ name: e2e-plan
 skills: [playwright-testing]
 description: Explore the application and create a structured E2E test plan in Markdown
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "plan E2E tests for this feature, what should we cover in playwright"
+  trigger_context: "new feature or page added without tests/e2e/ coverage"
 ---
 
 # e2e-plan

package/.agent-src/commands/estimate-ticket.md

@@ -3,6 +3,10 @@ name: estimate-ticket
 skills: [estimate-ticket]
 description: Estimate a Jira/Linear ticket before sprint planning — size + risk + split recommendation + uncertainty, sibling to /refine-ticket, ends with a close-prompt
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "how big is this ticket, estimate PROJ-123, should we split this"
+  trigger_context: "ticket key matching [A-Z]+-[0-9]+ in the prompt and no plan yet"
 ---
 
 # estimate-ticket
@@ -77,4 +81,3 @@ persona voices) plus the close-prompt. Stop there. Do **not** chain into
 - [`refine-ticket`](refine-ticket.md) — sibling; run first if the ticket is vague
 - [`jira-ticket`](jira-ticket.md) — ticket loader this command delegates to
 - [`feature-plan`](feature-plan.md) — downstream planning
-- [`road-to-ticket-refinement.md`](../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap

package/.agent-src/commands/feature-dev.md

@@ -3,6 +3,10 @@ name: feature-dev
 description: Full 7-phase feature development workflow for complex features.
 skills: [laravel, php-coder]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "build this feature end-to-end, run the full feature workflow"
+  trigger_context: "long-form feature description spanning multiple components"
 ---
 # /feature-dev
 

package/.agent-src/commands/feature-explore.md

@@ -3,6 +3,10 @@ name: feature-explore
 skills: [laravel]
 description: Brainstorm and explore a feature idea before committing to a full plan
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "brainstorm this idea, explore this feature concept"
+  trigger_context: "open-ended feature idea without acceptance criteria"
 ---
 
 # feature-explore

package/.agent-src/commands/feature-plan.md

@@ -3,6 +3,10 @@ name: feature-plan
 skills: [feature-planning]
 description: Interactively plan a feature — research, discuss, and create a structured feature document
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "plan this feature, create a feature spec for X"
+  trigger_context: "feature idea referenced and no plan doc exists"
 ---
 
 # feature-plan

package/.agent-src/commands/feature-refactor.md

@@ -3,6 +3,10 @@ name: feature-refactor
 skills: [laravel, php-coder]
 description: Refine and update an existing feature plan through interactive discussion
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "update the feature plan, refine the feature spec"
+  trigger_context: "existing agents/features/*.md referenced in the prompt"
 ---
 
 # feature-refactor

package/.agent-src/commands/feature-roadmap.md

@@ -3,6 +3,10 @@ name: feature-roadmap
 skills: [agent-docs-writing]
 description: Generate implementation roadmap(s) from a feature plan and link them
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "turn this feature into a roadmap, generate the implementation roadmap"
+  trigger_context: "existing feature plan without linked roadmap"
 ---
 
 # feature-roadmap
@@ -172,6 +176,8 @@ What's next?
 ### Rules
 
 - **Do NOT commit or push.**
+- **Do NOT include commit steps in the roadmap** unless the user explicitly
+  requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
 - **Do NOT modify the feature plan** beyond updating the Roadmaps section and status.
 - **Always link roadmaps back to the feature** and vice versa.
 - **Use the roadmap template** from `agents/roadmaps/template.md`.

package/.agent-src/commands/fix-ci.md

@@ -3,6 +3,10 @@ name: fix-ci
 skills: [github-ci, quality-tools]
 description: Fetch CI errors from GitHub Actions and fix them
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "CI is failing, fix the GitHub Actions errors, the pipeline is red"
+  trigger_context: "open PR with failing checks"
 ---
 
 # fix-ci

package/.agent-src/commands/fix-portability.md

@@ -2,6 +2,9 @@
 name: fix-portability
 description: Find and fix project-specific references in shared .augment/ package files
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Package-internal — only the event4u/agent-config repo runs this."
 ---
 
 # fix-portability
@@ -89,8 +92,8 @@ python3 scripts/compress.py --mark-done "{relative_path}"
 
 ## Rules
 
-- **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
-- **Run `bash scripts/compress.sh --sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Always fix in `.agent-src.uncompressed/`** — never edit `.augment/` directly.
+- **Copy to `.augment/`** after fixing.
 - **Do NOT commit or push.**
 - **`agents/` directory is allowed** to have project-specific references — skip it.
 - **Do NOT fix references in code blocks** unless the code block is clearly a template.

package/.agent-src/commands/fix-pr-bot-comments.md

@@ -3,6 +3,10 @@ name: fix-pr-bot-comments
 skills: [php-coder, quality-tools]
 description: Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "address the Copilot/Greptile comments, fix the bot review feedback"
+  trigger_context: "open PR with bot review comments unresolved"
 ---
 
 # fix-pr-bot-comments

package/.agent-src/commands/fix-pr-comments.md

@@ -3,6 +3,10 @@ name: fix-pr-comments
 skills: [php-coder]
 description: Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix all PR review comments, resolve the review feedback"
+  trigger_context: "open PR with unresolved comments (bot + human)"
 ---
 
 # fix-pr-comments

package/.agent-src/commands/fix-pr-developer-comments.md

@@ -3,6 +3,10 @@ name: fix-pr-developer-comments
 skills: [php-coder]
 description: Fix and reply to human reviewer comments on a GitHub PR
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix the human reviewer comments, address the developer feedback"
+  trigger_context: "open PR with unresolved human-reviewer comments"
 ---
 
 # fix-pr-developer-comments

package/.agent-src/commands/fix-references.md

@@ -2,6 +2,9 @@
 name: fix-references
 description: Find and fix broken cross-references in .augment/ and agents/ files
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Package-internal — only the event4u/agent-config repo runs this."
 ---
 
 # fix-references

package/.agent-src/commands/fix-seeder.md

@@ -3,6 +3,10 @@ name: fix-seeder
 skills: [eloquent]
 description: Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "the seeder is broken, foreign key errors in seeders"
+  trigger_context: "seeder error output or recent edits in database/seeders/"
 ---
 
 # fix-seeder

package/.agent-src/commands/implement-ticket.md

@@ -1,8 +1,12 @@
 ---
 name: implement-ticket
 skills: [refine-ticket, feature-planning]
-description: Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `implement_ticket` Python engine, block-on-ambiguity, no auto-git.
+description: Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, block-on-ambiguity, no auto-git.
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "implement this ticket, setze ticket X um, build PROJ-123"
+  trigger_context: "ticket key matching [A-Z]+-[0-9]+ in branch name or prompt"
 ---
 
 # implement-ticket
@@ -30,25 +34,45 @@ markdown. If no input resolves:
 ### 2. Prepare the state file
 
 The engine persists everything in a JSON state file (default:
-`.implement-ticket-state.json` in the repo root). Two cases:
+`.work-state.json` in the repo root). The resolved ticket lives inside
+the work-state envelope as `input.kind="ticket"`, `input.data={id,
+title, body, acceptance_criteria}` — the engine builds that wrapping
+internally when given `--ticket-file`, so callers pass the ticket JSON
+unchanged.
 
-- **Fresh run** — state file does not exist. Write the resolved ticket to
+Three cases, in this order:
+
+- **Legacy state file present** — `.implement-ticket-state.json` exists
+  and `.work-state.json` does not. Migrate before doing anything else:
+
+  ```bash
+  ./agent-config migrate-state
+  ```
+
+  Writes `.work-state.json` and renames the source to
+  `.implement-ticket-state.json.bak`. Idempotent and safe to skip if
+  already done. After this, treat the run as **Resume**.
+- **Fresh run** — no state file at all. Write the resolved ticket to
   `ticket.json` (id, title, body, acceptance_criteria) and pass it via
   `--ticket-file ticket.json`. Honour `roles.active_role` from
   `.agent-settings.yml` via `--persona`.
-- **Resume** — state file exists. Do **not** pass `--ticket-file` or
-  `--persona`; mid-flight persona switches are refused by the engine.
+- **Resume** — `.work-state.json` exists. Do **not** pass `--ticket-file`
+  or `--persona`; mid-flight persona switches are refused by the engine.
 
 ### 3. Drive the Option-A dispatch loop
 
 Run the engine with the state file on every iteration:
 
 ```bash
-PYTHONPATH=scripts python3 -m implement_ticket \
-    --state-file .implement-ticket-state.json \
+./agent-config implement-ticket \
+    --state-file .work-state.json \
     [--ticket-file ticket.json --persona <name>]   # first call only
 ```
 
+The dispatcher wires `PYTHONPATH` and routes to the engine module
+internally. `./agent-config` is the only supported entry point in
+consumer repos — do not call the engine module directly.
+
 Then branch on the exit code:
 
 | Exit | Meaning | Action |
@@ -88,15 +112,14 @@ wrote it.
 
 ### 5. Final report + close-prompt
 
-On exit `0`, the engine prints the delivery report (nine fixed sections
-per [`implement-ticket-flow`](../../agents/contexts/implement-ticket-flow.md#delivery-report-schema)).
+On exit `0`, the engine prints the delivery report (nine fixed sections).
 Surface it unchanged. Append the close-prompt:
 
 ```
 > 1. /commit — stage + commit per the delivery report
 > 2. /create-pr — open a pull request from this branch
 > 3. Keep working — I'll hold the state file for the next /implement-ticket
-> 4. Discard — delete .implement-ticket-state.json
+> 4. Discard — delete .work-state.json (and any .implement-ticket-state.json.bak)
 ```
 
 **Never run `/commit` or `/create-pr` without the user choosing them.**
@@ -115,6 +138,12 @@ permission-gated.
   fresh run; never accept a `--persona` flag from the user mid-flight.
 - Memory section in the report is absent when no hit changed an outcome.
   That is by design — don't pad it.
+- When `telemetry.artifact_engagement.enabled: true` in
+  `.agent-settings.yml`, emit one `./agent-config telemetry:record` per
+  boundary (per phase-step or per task — see `granularity`) with the
+  consulted+applied artefact ids. Full contract in
+  [`artifact-engagement-recording`](../rules/artifact-engagement-recording.md).
+  Default-off; absent setting is a silent no-op.
 
 ## Examples
 
@@ -126,8 +155,5 @@ permission-gated.
 
 ## See also
 
-- [`implement-ticket-flow`](../../agents/contexts/implement-ticket-flow.md) — flow contract + directive semantics
-- [`adr-implement-ticket-runtime`](../../agents/contexts/adr-implement-ticket-runtime.md) — runtime choice
 - [`refine-ticket`](refine-ticket.md), [`feature-plan`](feature-plan.md), [`tests-execute`](tests-execute.md), [`review-changes`](review-changes.md) — skills the directives delegate to
 - [`commit`](commit.md), [`create-pr`](create-pr.md) — post-delivery commands the user runs explicitly
-- [`road-to-implement-ticket`](../../agents/roadmaps/road-to-implement-ticket.md) — governing roadmap

package/.agent-src/commands/jira-ticket.md

@@ -3,6 +3,10 @@ name: jira-ticket
 skills: [laravel]
 description: Read Jira ticket from branch name, analyze linked Sentry issues, implement feature or fix bug
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "implement the ticket on this branch, work on the Jira ticket from the branch"
+  trigger_context: "branch name matching feat/PROJ-123-* or similar"
 ---
 
 # jira-ticket

package/.agent-src/commands/judge.md

@@ -3,6 +3,9 @@ name: judge
 skills: [subagent-orchestration]
 description: Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Sibling of /review-changes — eligibility routed there; keep this explicit."
 ---
 
 # judge

package/.agent-src/commands/memory-add.md

@@ -3,6 +3,10 @@ name: memory-add
 description: Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decisions, incident-learnings, product-rules)
 skills: [file-editor]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "remember this for later, add this to engineering memory, capture this learning"
+  trigger_context: "post-incident or post-decision conversation"
 ---
 
 # /memory-add
@@ -89,7 +93,7 @@ On confirmation:
 
 - Append the entry to the chosen layout (single-file: append under
   `entries:`; sharded: write `agents/memory/<type>/<hash>.yml`).
-- Run `python3 scripts/check_memory.py --path agents/memory`.
+- Run `./agent-config memory:check --path agents/memory`.
 - On non-zero exit: show the error, **revert** the write, return to
   step 3 or 4 depending on the failure.
 - On zero exit: report the entry `id` and path, remind the user to
@@ -126,5 +130,3 @@ link resolves. Broken link → block and ask the user to fix.
 - [`capture-learnings`](../rules/capture-learnings.md) — when a
   learning is better captured as an `incident-learnings` entry vs a
   rule/skill proposal
-- [`road-to-engineering-memory.md`](../../agents/roadmaps/road-to-engineering-memory.md)
-  — Phase 3 writer ergonomics

package/.agent-src/commands/memory-full.md

@@ -3,6 +3,9 @@ name: memory-full
 description: Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analysis, never auto-triggered
 skills: []
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Description states 'never auto-triggered' — opt-in deep-load only."
 ---
 
 # /memory-full
@@ -42,7 +45,7 @@ in the entry count and the signal-to-noise degrades fast on large types.
 Before loading, count the entries:
 
 ```bash
-python3 scripts/memory_lookup.py --types <type> --format json | \
+./agent-config memory:lookup --types <type> --format json | \
   python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
 ```
 
@@ -59,7 +62,7 @@ If the count exceeds 25, warn:
 ### 3. Load
 
 ```bash
-python3 scripts/memory_lookup.py --types <type> --format yaml
+./agent-config memory:lookup --types <type> --format yaml
 ```
 
 Render the output verbatim, grouped by status (`active` first, then

package/.agent-src/commands/memory-promote.md

@@ -3,6 +3,9 @@ name: memory-promote
 description: Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the admission gate.
 skills: [file-editor]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Curation pipeline — overlaps /memory-add; keep explicit."
 ---
 
 # /memory-promote
@@ -23,7 +26,7 @@ entry.
   (`/bug-fix`, `/do-and-judge`, incident-role exit).
 - The user can name the intake `id` (e.g., `sig-abc123`). If not,
   route to the read side:
-  `python3 scripts/memory_lookup.py --types <type> --key <hint>` to
+  `./agent-config memory:lookup --types <type> --key <hint>` to
   surface candidates.
 
 ## Steps
@@ -40,7 +43,7 @@ entry.
 ### 2. Run the admission gate
 
 ```bash
-python3 scripts/check_memory_proposal.py --intake-id <sig-id>
+./agent-config memory:check-proposal --intake-id <sig-id>
 ```
 
 If the gate reports failures, show them to the user numbered and ask:
@@ -76,7 +79,7 @@ Compute the content hash and write a **one-entry file** at
 `agents/memory/<type>/<hash>.yml`:
 
 ```bash
-HASH=$(python3 scripts/memory_hash.py --yaml /tmp/draft.yml)
+HASH=$(./agent-config memory:hash --yaml /tmp/draft.yml)
 mkdir -p agents/memory/<type>
 mv /tmp/draft.yml agents/memory/<type>/${HASH}.yml
 ```
@@ -91,7 +94,7 @@ mv /tmp/draft.yml agents/memory/<type>/${HASH}.yml
   existence and refuse with a migration hint:
   `⚠️  agents/memory/<type>.yml exists — migrate to content-
   addressed first (`/memory-migrate <type>`)`.
-- **Schema validation** — run `python3 scripts/check_memory.py
+- **Schema validation** — run `./agent-config memory:check
   --path agents/memory/<type>/${HASH}.yml` before commit. On failure,
   delete the file and stop.
 
@@ -140,5 +143,3 @@ git push -u origin memory/promote-<curated-id>
 - [`/propose-memory`](propose-memory.md) — write-side entry point.
 - [`/memory-add`](memory-add.md) — direct curated write (skips intake).
 - [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
-- [`road-to-agent-memory-integration`](../../../agents/roadmaps/road-to-agent-memory-integration.md)
-  — Phase 3.

package/.agent-src/commands/mode.md

@@ -2,6 +2,9 @@
 name: mode
 description: Set the active role mode — prints the contract, lists default skills, and refuses work outside the contract (see role-contracts)
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Role-mode switch is a deliberate context change."
 ---
 
 # /mode

package/.agent-src/commands/module-create.md

@@ -3,6 +3,10 @@ name: module-create
 skills: [laravel]
 description: Create a new module from .module-template with interactive setup
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create a new module, scaffold a module for X"
+  trigger_context: "prompt mentions a new domain area without an existing module"
 ---
 
 # module-create

package/.agent-src/commands/module-explore.md

@@ -3,6 +3,10 @@ name: module-explore
 skills: [laravel]
 description: Explore a module — load its structure, docs, and context into the current conversation
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "show me the X module, load the module context"
+  trigger_context: "existing Modules/<Name>/ referenced in the prompt"
 ---
 
 # module-explore

package/.agent-src/commands/onboard.md

@@ -3,8 +3,13 @@ name: onboard
 description: First-run setup for a developer on this project — captures name, IDE, bot-icon preference, rtk, cost_profile, and learning opt-out, then sets onboarding.onboarded=true
 skills: [file-editor]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Gated by the onboarding-gate rule already; never inferred from prose."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /onboard
 
 Centralized first-run flow. Bundles what used to be scattered "ask once"
@@ -153,6 +158,27 @@ directly — the agent follows the merge rules in `layered-settings` when
 you ask it to change a value.
 ```
 
+### 9. Maintainer-only feature pointer
+
+Print a one-screen hint after the summary — no question, no prompt, just a
+pointer for maintainers who want to opt into the artefact-engagement
+telemetry layer. Consumers can ignore it; the feature is **default-off**
+and stays off unless explicitly enabled.
+
+```
+ℹ️  Maintainer telemetry (opt-in)
+
+  telemetry.artifact_engagement is off by default. If you maintain skills,
+  rules, or commands and want to see which ones the agent actually applies,
+  set telemetry.artifact_engagement.enabled: true in .agent-settings.yml.
+
+  The log is local-only JSONL — nothing uploaded, nothing shared across
+  projects. Reports: ./agent-config telemetry:report
+  Contract + privacy floor: docs/contracts/artifact-engagement-flow.md
+```
+
+Skip this block in cloud surfaces (no settings file, no log path).
+
 ## Gotchas
 
 - `.agent-settings.yml` is git-ignored. This command never commits.
@@ -163,6 +189,13 @@ you ask it to change a value.
 - Never overwrite a non-empty value without asking (applies to `user_name`
   and `ide`).
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` to write, no `onboarding.onboarded` key to
+flip, and no local IDE/rtk environment to capture. First-run setup is a
+local-agent concern; the cloud agent should proceed without invoking it.
+
 ## See also
 
 - [`onboarding-gate`](../rules/onboarding-gate.md) — rule that triggers this command

package/.agent-src/commands/optimize-agents.md

@@ -3,6 +3,10 @@ name: optimize-agents
 description: Audits agent infrastructure — measures token overhead, checks rule triggers, verifies AGENTS.md. Suggest only, never auto-apply.
 skills: [copilot-agents-optimization, agents-audit, agent-docs-writing, quality-tools]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "audit agent infrastructure, tune the agent setup"
+  trigger_context: "maintainer working on .augment/ files"
 ---
 
 # /optimize-agents