@event4u/agent-config 1.19.0 → 1.20.0

package/docs/contracts/memory-visibility-v1.md

@@ -11,10 +11,9 @@ Complements [`agent-memory-contract.md`](agent-memory-contract.md):
 that doc describes the **CLI surface and backend states**; this doc
 describes the **operator-facing surface** the engine emits per turn.
 
-**Scope.** Defines the line shape, the privacy floor, the opt-out
-toggle, and the interaction with the chat-history heartbeat. Does
-**not** define how memory entries are scored or routed — that is the
-sibling agent-memory package.
+**Scope.** Defines the line shape, the privacy floor, and the opt-out
+toggle. Does **not** define how memory entries are scored or routed —
+that is the sibling agent-memory package.
 
 Last refreshed: 2026-05-04.
 
@@ -78,28 +77,13 @@ Off-mode does not silence the underlying memory calls; it only stops
 the line from rendering. The decision-trace JSON still records the
 counts and ids for downstream metrics.
 
-## Interaction with chat-history heartbeat
-
-The chat-history heartbeat (`📒` marker) and the memory-visibility
-line are **independent**:
-
-- Heartbeat fires on cadence boundaries
-  (`per_turn` / `per_phase` / `per_tool`).
-- Visibility line fires whenever `asks ≥ 1` for the current turn,
-  regardless of cadence.
-- Both render on the same reply when both fire — heartbeat first,
-  visibility line second, separated by a single newline.
-
-The visibility line is **not** part of the heartbeat payload — that
-keeps the heartbeat contract bytes-stable.
-
 ## Cadence interaction
 
-| Cost profile | Visibility line | Heartbeat |
-|---|---|---|
-| `lean` | suppress unless `asks ≥ 3` | per-phase |
-| `standard` | always when `asks ≥ 1` | per-turn |
-| `verbose` | always when `asks ≥ 1` | per-tool |
+| Cost profile | Visibility line |
+|---|---|
+| `lean` | suppress unless `asks ≥ 3` |
+| `standard` | always when `asks ≥ 1` |
+| `verbose` | always when `asks ≥ 1` |
 
 Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
 key. Default is `standard`.

package/docs/customization.md

@@ -53,7 +53,7 @@ those sections.
 | `personal.open_edited_files` | `false` | Open edited files in IDE |
 | `personal.ide` | *(empty)* | IDE for file opening (`cursor`, `code`, `phpstorm`) |
 | `pipelines.skill_improvement` | `true` | Post-task learning capture. Included in every profile except `custom`. |
-| `chat_history.enabled` | `true` | Persistent JSONL log at `.agent-chat-history` for crash recovery. |
+| `chat_history.enabled` | `true` | Persistent JSONL log at `agents/.agent-chat-history` for crash recovery. |
 | `chat_history.frequency` | per profile | Logging granularity: `per_turn`, `per_phase`, or `per_tool` (see matrix below). |
 | `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
 | `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 58 rules. No configuration needed.
+This is enforced automatically by 56 rules. No configuration needed.
 
 ---
 
@@ -151,41 +151,33 @@ Your agent now understands slash commands:
 | `/optimize skills` | Audit skills, find duplicates, run linter |
 | `/feature plan` | Interactively plan a feature |
 | `/quality-fix` | Run and fix all quality checks |
-| `/chat-history` | Inspect the persistent chat-history log |
-| `/chat-history-resume` | Recover context after a crashed or switched session |
-| `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
+| `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 95 active commands](../.agent-src/commands/)
+→ [Browse all 94 active commands](../.agent-src/commands/)
 
 ---
 
-## Crash recovery — `.agent-chat-history`
+## Crash recovery — `agents/.agent-chat-history`
 
 When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
 for every profile), the agent keeps a JSONL log of your conversation in
-`.agent-chat-history` at the project root. The file is git-ignored and
-rotates at the size configured in the profile (`128 KB` on `minimal`,
-`256 KB` on `balanced`, `512 KB` on `full`).
-
-When a chat opens and finds an existing log, the host agent is
-instructed to run a 4-state ownership check and choose the right
-flow:
-
-- **match** — this chat already owns the file. Append silently.
-- **foreign** — a different session's file. You get 3 options:
-  Resume (adopt), New start (archive + init), Ignore (skip logging).
-- **returning** — this chat once owned the file, but another session
-  took over in between. You get 3 options: Merge (your history in front
-  of the foreign entries), Replace (wipe foreign entries, keep yours
-  only), Continue (just leave the file and append from now on).
-- **missing** — no file yet. Init and proceed.
-
-Run `/chat-history-resume` to walk through the prompts explicitly, or
-let the agent ask on the first turn of a new chat. All merge/replace/
-resume paths read the on-disk entries into context before any write.
-
-See the [`chat-history` rule](../.agent-src/rules/chat-history-ownership.md) and
-[`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
+`agents/.agent-chat-history`. The file is git-ignored and rotates at the
+size configured in the profile (`128 KB` on `minimal`, `256 KB` on
+`balanced`, `512 KB` on `full`).
+
+Logging is **hook-only**: a structural Augment hook fires on
+`session_start` and binds the log to the current session via auto-adopt
+— no agent prompts, no ownership questions. The file is rewritten
+transparently if the fingerprint does not match (fresh chat) and
+otherwise appended to.
+
+Run `/chat-history` (a.k.a. `/chat-history show`) any time to inspect
+the log size, last entries, and current fingerprint. For the rare case
+where auto-adopt misfires (corrupted file, hook misconfiguration), run
+`./agent-config chat-history:adopt` as the manual recovery lever.
+
+See [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+and [`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---
 

package/docs/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -106,7 +106,7 @@ Agent: Bevor ich die Roadmap übergebe:
 - Welcher Branch?
 - Soll ich PRs erwähnen?
 - Welches Modell für die Fortsetzung?
-- Soll ich .agent-chat-history zitieren?
+- Soll ich agents/.agent-chat-history zitieren?
 
 Antworte als 1, 2, 3, 4.
 ```

package/docs/hook-payload-capture.md

@@ -0,0 +1,221 @@
+# Hook payload capture guide
+
+**Purpose:** walk through the live-session payload capture for one platform
+in roughly 5 minutes, so the corresponding entry in
+[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+can move from `docs-verified` to `payload-verified`.
+
+**Scope:** Cursor · Cline · Windsurf · Gemini CLI. Augment Code and Claude
+Code already shipped as `docs-verified` in Phase 1 of the now-archived
+[`road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md).
+Cowork is upstream-blocked separately
+([`#40495`](https://github.com/anthropics/claude-code/issues/40495)) and
+not in scope here.
+
+**Why this is opportunistic:** the payload-verified upgrade is a nice-to-have.
+The shipping `docs-verified` extractors already match the vendor docs —
+captures are insurance against silent vendor-side schema drift. Pick one
+platform when convenient; do not run all four in one sitting unless you
+already have all four IDEs installed and licensed.
+
+## Pre-flight (one-time, ~30 seconds)
+
+```bash
+cd /path/to/agent-config
+
+# Confirm the dispatcher is wired in this project (idempotent — safe to rerun).
+# Replace <platform> with cursor / cline / windsurf / gemini as appropriate
+# when you reach that platform's section.
+python3 scripts/install.py --<platform>
+
+# Confirm the trampoline + project-scope hooks file landed.
+./agent-config hooks:status | grep -E "^[ ✓✅⚠️❌·] (cursor|cline|windsurf|gemini)"
+```
+
+`hooks:status` should report `installed` for the platform you just wired
+(or `missing` if the project-scope file did not land — in that case rerun
+the install with `--force`).
+
+## Common capture loop (steps reused on every platform)
+
+```bash
+# 1. Pick a per-platform capture dir (gitignored; never committed).
+export AGENT_HOOK_CAPTURE_DIR="$HOME/.agent-config-captures/<platform>"
+mkdir -p "$AGENT_HOOK_CAPTURE_DIR"
+
+# 2. Restart / reload the platform so it picks up the env var.
+#    Per-platform commands below.
+
+# 3. Run ONE short, boring session in the platform.
+#    Recommended prompt: "echo hello" or "what time is it".
+#    Goal is to capture the envelope shape, not interesting content.
+
+# 4. Confirm capture files exist.
+ls -1 "$AGENT_HOOK_CAPTURE_DIR" | head
+
+# 5. Redact (replaces user-content fields with <REDACTED>;
+#    envelope keys preserved).
+python3 scripts/redact_hook_capture.py "$AGENT_HOOK_CAPTURE_DIR" --strict
+
+# 6. Pick the smallest representative file.
+ls -1Sr "$AGENT_HOOK_CAPTURE_DIR"/*.redacted.json | head -1
+
+# 7. cat it; copy the JSON; paste into the archived roadmap section
+#    (see § Where to paste below).
+```
+
+The redaction step is non-negotiable. The goal is to lock schemas, not to
+archive conversations.
+
+## Per-platform notes
+
+### Cursor (~5 min)
+
+- **Install:** `python3 scripts/install.py --cursor` (project) or
+  `--cursor-user-hooks` (covers every project you open).
+- **Restart:** quit Cursor (Cmd+Q on macOS), then relaunch from the
+  shell where you exported `AGENT_HOOK_CAPTURE_DIR` so the env var
+  propagates to the renderer process. Reopening a window from the
+  Dock will not inherit the env.
+- **Trigger event:** type a prompt in Cursor's agent panel and let it
+  finish. Expected captures: one `sessionStart`, one
+  `beforeSubmitPrompt`, one `afterAgentResponse` and/or `stop`,
+  zero or more `postToolUse`.
+- **File pattern:** `cursor__afterAgentResponse__<ts>__<pid>.json` is
+  the most useful one to paste.
+- **CLI vs IDE:** Cursor CLI fires only
+  `beforeShellExecution`/`afterShellExecution` — for the
+  per-turn payload you need the IDE.
+
+### Cline (~5 min)
+
+- **Install:** `python3 scripts/install.py --cline` (project) or
+  `--cline-user-hooks` (user-scope, covers every workspace).
+- **Restart:** in VS Code or JetBrains, run "Developer: Reload
+  Window" (Cmd+Shift+P) from a terminal where the env is exported.
+  Cline reads hooks at task start, so a fresh task is required —
+  closing and reopening the side panel is not enough.
+- **Trigger event:** start a new Cline task and let one turn complete.
+  Cline calls them "tasks" not "sessions"; the equivalent boundaries
+  are `TaskStart` → `UserPromptSubmit` → `PostToolUse`* →
+  `TaskComplete`.
+- **File pattern:** `cline__TaskComplete__<ts>__<pid>.json` if you let
+  the task finish; `cline__UserPromptSubmit__<ts>__<pid>.json` is also
+  acceptable (carries the `prompt` envelope).
+- **Windows caveat:** hooks are unsupported on Windows
+  ([`cline/cline#8073`](https://github.com/cline/cline/issues/8073));
+  capture from macOS or Linux.
+
+### Windsurf (~5 min)
+
+- **Install:** `python3 scripts/install.py --windsurf` (project) or
+  `--windsurf-user-hooks` (user-scope at `~/.codeium/windsurf/hooks.json`).
+- **Restart:** quit Cascade fully, then relaunch from the shell with
+  the env exported. The `pre_user_prompt` event fires on every turn —
+  no full restart needed once Cascade is up, but the *first* turn after
+  launch must be the captured one.
+- **Trigger event:** ask Cascade one short question and let it answer.
+  Expected captures: `pre_user_prompt`,
+  `post_cascade_response_with_transcript`. The
+  `_with_transcript` variant is the more useful one to paste because it
+  carries the full response inline.
+- **File pattern:** `windsurf__post_cascade_response_with_transcript__<ts>__<pid>.json`.
+- **Async caveat:** `post_cascade_response` fires asynchronously off
+  the critical path. The capture file might land a second or two after
+  the response renders — wait briefly before running the redact step.
+
+### Gemini CLI (~5 min)
+
+- **Install:** `python3 scripts/install.py --gemini` (project) or
+  `--gemini-user-hooks` (user-scope at `~/.gemini/settings.json`).
+- **Restart:** Gemini CLI is invoked per command — no daemon to
+  restart. Just open a new shell with `AGENT_HOOK_CAPTURE_DIR`
+  exported and run the next session there.
+- **Trigger event:** any short Gemini CLI session
+  (`gemini "what time is it"` or similar). Hooks fire on
+  `SessionStart` → `BeforeAgent` → `AfterTool`* → `AfterAgent` →
+  `SessionEnd`.
+- **File pattern:** `gemini__AfterAgent__<ts>__<pid>.json` carries the
+  per-turn close envelope and is the recommended paste target.
+- **Advisory hooks:** `SessionStart` and `SessionEnd` are advisory only
+  in Gemini CLI — do not be alarmed if those captures look thinner than
+  the others.
+
+## Where to paste the redacted payload
+
+The roadmap is now archived. Paste under the matching phase:
+
+[`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)
+
+- Cursor → § Phase 2 — Cursor
+- Cline → § Phase 3 — Cline
+- Windsurf → § Phase 4 — Windsurf
+- Gemini CLI → § Phase 5 — Gemini CLI
+
+In the chosen phase, paste the redacted JSON inside a fenced
+`json` block under a heading like `### <Platform> payload shape (captured 2026-MM-DD)`,
+then flip the `[ ] Optional upgrade — payload-verified` checkbox to
+`[x]`.
+
+Then update the matching row in
+[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md):
+the `Verification` column moves from `docs-verified` to
+`payload-verified`.
+
+If the captured shape diverges from the docs-verified extractor
+branch, that is the trigger for a code patch — open a tiny new roadmap
+under `agents/roadmaps/` for the divergence work, do **not** edit the
+archived roadmap to track new code work
+(see [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md)).
+
+## Final verify
+
+After pasting and flipping the checkbox:
+
+```bash
+# Lint gates must stay green.
+python3 scripts/lint_hook_manifest.py
+python3 scripts/check_references.py
+python3 scripts/check_portability.py
+
+# Tests still green.
+python3 -m pytest tests/hooks/ -q
+
+# Optional: regenerate the dashboard if the archived roadmap's
+# checkbox change should bubble up. Iron Law from
+# `roadmap-progress-sync` says yes if it does.
+./agent-config roadmap:progress
+```
+
+Per
+[`commit-policy`](../.agent-src/rules/commit-policy.md):
+do **not** commit unless explicitly told to. The user owns the commit
+step.
+
+## Cleanup after capture
+
+```bash
+# Raw captures (not redacted) contain real prompt content.
+# Either delete the directory or leave it for repeat captures.
+rm -rf "$AGENT_HOOK_CAPTURE_DIR"
+
+# Or keep redacted ones only:
+# find "$AGENT_HOOK_CAPTURE_DIR" -type f ! -name '*.redacted.json' -delete
+
+# Unset the env var when done so subsequent sessions do not capture.
+unset AGENT_HOOK_CAPTURE_DIR
+```
+
+The capture directory is gitignored project-wide; raw captures are
+never accidentally committed. The redaction step is still mandatory
+before paste because the redacted output goes into a tracked file
+(the archived roadmap) and would otherwise leak.
+
+## Sources
+
+- Capture engine: [`scripts/hooks/dispatch_hook.py`](../scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
+- Redactor: [`scripts/redact_hook_capture.py`](../scripts/redact_hook_capture.py)
+- Per-platform install logic: [`scripts/install.py`](../scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
+- Platform matrix + payload schemas: [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+- Hook architecture: [`docs/contracts/hook-architecture-v1.md`](contracts/hook-architecture-v1.md)
+- Archived roadmap with per-phase paste sections: [`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)

package/docs/migrations/commands-1.15.0.md

@@ -85,18 +85,23 @@ the deprecation cycle for Phase 1 closes. Tracked in
 [`agents/roadmaps/archive/road-to-governance-cleanup.md`](../../agents/roadmaps/archive/road-to-governance-cleanup.md)
 § F2.
 
-## Related rule split — `chat-history` (post-1.15.0)
-
-The monolithic `rules/chat-history.md` was split into three sibling
-`always` rules in the post-1.15.0 optimization phase:
-
-- [`chat-history-ownership`](../../.agent-src/rules/chat-history-ownership.md) — sole owner of file I/O + first-turn handshake.
-- [`chat-history-cadence`](../../.agent-src/rules/chat-history-cadence.md) — when to persist (SessionStart / StepEnd / append boundaries).
-- [`chat-history-visibility`](../../.agent-src/rules/chat-history-visibility.md) — heartbeat marker contract for user-facing reporting.
-
-Decision record: [`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md).
-Cross-references in commands and contexts now point to
-`chat-history-ownership` as the entry point.
+## Related rule split — `chat-history` (post-1.15.0, superseded)
+
+> **Superseded · 2026-05-04** by
+> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> The three sibling rules (`chat-history-ownership`,
+> `chat-history-cadence`, `chat-history-visibility`) and the heartbeat
+> marker no longer exist. Persistence is now a pure platform-hook
+> contract — `session_start` auto-adopts foreign sessions silently;
+> the agent never reads or writes `agents/.agent-chat-history` cooperatively.
+> Manual recovery lever: `./agent-config chat-history:adopt`.
+
+For historical context: the monolithic `rules/chat-history.md` was
+first split into three sibling `always` rules in the post-1.15.0
+optimization phase, recorded in
+[`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md)
+(also marked superseded). The hook-only roadmap then collapsed all
+three rules into structural-only artefacts.
 
 ## Rollback
 

package/docs/skills-catalog.md

@@ -1,6 +1,6 @@
 # Skills Catalog
 
-All **128 skills** available in this package, in alphabetical order.
+All **129 skills** available in this package, in alphabetical order.
 Click a skill name to open its SKILL.md and read the full guidance.
 
 > **Regenerate:** `python3 scripts/generate_catalog.py`
@@ -10,6 +10,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 |---|---|
 | [`adversarial-review`](../.agent-src/skills/adversarial-review/SKILL.md) | ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback. |
 | [`agent-docs-writing`](../.agent-src/skills/agent-docs-writing/SKILL.md) | Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure. |
+| [`ai-council`](../.agent-src/skills/ai-council/SKILL.md) | Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'. |
 | [`analysis-autonomous-mode`](../.agent-src/skills/analysis-autonomous-mode/SKILL.md) | ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work. |
 | [`analysis-skill-router`](../.agent-src/skills/analysis-skill-router/SKILL.md) | Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'. |
 | [`api-design`](../.agent-src/skills/api-design/SKILL.md) | Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design. |
@@ -18,7 +19,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) | Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling. |
 | [`authz-review`](../.agent-src/skills/authz-review/SKILL.md) | Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows. |
 | [`aws-infrastructure`](../.agent-src/skills/aws-infrastructure/SKILL.md) | Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS. |
-| [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) | Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic. |
+| [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) | Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic. |
 | [`blast-radius-analyzer`](../.agent-src/skills/blast-radius-analyzer/SKILL.md) | Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency. |
 | [`bug-analyzer`](../.agent-src/skills/bug-analyzer/SKILL.md) | Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs. |
 | [`check-refs`](../.agent-src/skills/check-refs/SKILL.md) | Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions. |
@@ -49,7 +50,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`feature-planning`](../.agent-src/skills/feature-planning/SKILL.md) | Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap. |
 | [`file-editor`](../.agent-src/skills/file-editor/SKILL.md) | Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled. |
 | [`finishing-a-development-branch`](../.agent-src/skills/finishing-a-development-branch/SKILL.md) | Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'. |
-| [`flux`](../.agent-src/skills/flux/SKILL.md) | Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives. |
+| [`flux`](../.agent-src/skills/flux/SKILL.md) | Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives. |
 | [`git-workflow`](../.agent-src/skills/git-workflow/SKILL.md) | Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git. |
 | [`github-ci`](../.agent-src/skills/github-ci/SKILL.md) | Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'. |
 | [`grafana`](../.agent-src/skills/grafana/SKILL.md) | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
@@ -72,7 +73,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`laravel-validation`](../.agent-src/skills/laravel-validation/SKILL.md) | Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it. |
 | [`learning-to-rule-or-skill`](../.agent-src/skills/learning-to-rule-or-skill/SKILL.md) | Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work. |
 | [`lint-skills`](../.agent-src/skills/lint-skills/SKILL.md) | Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata. |
-| [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation. |
+| [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation. |
 | [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
 | [`mcp`](../.agent-src/skills/mcp/SKILL.md) | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
 | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |

package/llms.txt

@@ -8,6 +8,7 @@ Catalog: docs/skills-catalog.md
 
 adversarial-review: ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback.
 agent-docs-writing: Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure.
+ai-council: Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'.
 analysis-autonomous-mode: ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work.
 analysis-skill-router: Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'.
 api-design: Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design.
@@ -16,7 +17,7 @@ api-testing: Use when writing API endpoint tests — integration tests, contract
 artisan-commands: Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling.
 authz-review: Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows.
 aws-infrastructure: Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS.
-blade-ui: Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic.
+blade-ui: Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic.
 blast-radius-analyzer: Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency.
 bug-analyzer: Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs.
 check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
@@ -47,7 +48,7 @@ fe-design: Reference for frontend-design heuristics — component architecture,
 feature-planning: Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap.
 file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
 finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'.
-flux: Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives.
+flux: Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives.
 git-workflow: Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git.
 github-ci: Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'.
 grafana: Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana.
@@ -70,7 +71,7 @@ laravel-scheduling: Use when configuring Laravel task scheduling — cron expres
 laravel-validation: Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it.
 learning-to-rule-or-skill: Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work.
 lint-skills: Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata.
-livewire: Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation.
+livewire: Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation.
 logging-monitoring: Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers.
 mcp: Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows.
 md-language-check: Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.19.0",
+    "version": "1.20.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/agent-config

@@ -68,7 +68,7 @@ Commands:
   refine-ticket:detect       Run the deterministic refine-ticket detection helper
   chat-history:hook          Platform hook entry point (read JSON from stdin)
                              Usage: chat-history:hook --platform <claude|augment|cursor|cline|windsurf|gemini>
-  chat-history:checkpoint    Append a phase-boundary entry to .agent-chat-history
+  chat-history:checkpoint    Append a phase-boundary entry to agents/.agent-chat-history
                              (CHECKPOINT fallback for platforms without native hooks)
   roadmap-progress:hook      PostToolUse hook entry point (read JSON from stdin)
                              Regenerates roadmaps-progress.md when a tool wrote under agents/roadmaps/

package/scripts/ai_council/_default_prices.py

@@ -1,7 +1,7 @@
 """Shipped baseline prices for the AI Council.
 
-This file is the bootstrap source for `.agent-prices.md` when the
-runtime file is missing. It is also the network-fallback source for
+This file is the bootstrap source for `agents/.agent-prices.md` when
+the runtime file is missing. It is also the network-fallback source for
 `scripts/update_prices.py` when the upstream feed (LiteLLM) is
 unreachable.
 
@@ -9,8 +9,8 @@ Prices are USD per **1 000 000** tokens. Models are identified by the
 exact `model:` string the user puts into `.agent-settings.yml`.
 
 Numbers below are a hand-curated snapshot — they will drift. The
-runtime never reads them directly once `.agent-prices.md` exists; the
-weekly refresh and user edits are the live source of truth.
+runtime never reads them directly once `agents/.agent-prices.md`
+exists; the weekly refresh and user edits are the live source of truth.
 """
 
 from __future__ import annotations

package/scripts/ai_council/clients.py

@@ -100,7 +100,7 @@ class ExternalAIClient(ABC):
 
     name: str = ""
     model: str = ""
-    billable: bool = True  # API-mode subclasses spend money; manual/playwright don't.
+    billable: bool = True  # API-mode subclasses spend money; manual doesn't.
 
     @abstractmethod
     def ask(

package/scripts/ai_council/modes.py

@@ -4,14 +4,13 @@ Each council member runs in exactly one transport mode per invocation:
 
 - ``api``      — direct SDK call against the provider's API (billable).
 - ``manual``   — copy-paste loop with the user as transport (free).
-- ``playwright`` — browser automation (Phase 2c, not yet wired).
 
 Resolution precedence — first non-empty wins:
 
     1. Invocation flag      e.g. ``/council mode:manual``
     2. Per-member setting   ``ai_council.members.<name>.mode``
     3. Global setting       ``ai_council.mode``
-    4. Built-in default     ``api``
+    4. Built-in default     ``manual``
 
 This mirrors how ``cost_profile`` resolves in
 ``.augment/guidelines/agent-infra/layered-settings.md``.
@@ -24,9 +23,9 @@ from __future__ import annotations
 
 from typing import Mapping
 
-VALID_MODES: frozenset[str] = frozenset({"api", "manual", "playwright"})
+VALID_MODES: frozenset[str] = frozenset({"api", "manual"})
 
-DEFAULT_MODE: str = "api"
+DEFAULT_MODE: str = "manual"
 
 
 class InvalidModeError(ValueError):

package/scripts/ai_council/pricing.py

@@ -1,18 +1,19 @@
 """Runtime pricing layer for the AI Council.
 
-Reads `.agent-prices.md` from the repo root, parses YAML frontmatter
-and the Markdown table, and exposes:
+Reads `agents/.agent-prices.md` from the repo root, parses YAML
+frontmatter and the Markdown table, and exposes:
 
-- `load_prices()`           — parse `.agent-prices.md` (bootstraps if missing)
+- `load_prices()`           — parse `agents/.agent-prices.md` (bootstraps if missing)
 - `estimate_input_tokens()` — chars / 4 heuristic
 - `estimate_cost()`         — input + output USD for a single member
 - `is_stale()`              — True if `last_updated` is older than the
                               most recent UTC Monday 00:00
-- `bootstrap_from_defaults()` — write a fresh `.agent-prices.md` from
-                              `_default_prices.DEFAULT_PRICES`
+- `bootstrap_from_defaults()` — write a fresh `agents/.agent-prices.md`
+                              from `_default_prices.DEFAULT_PRICES`
 
 The orchestrator never reads `_default_prices` directly. It always
-goes through `load_prices()` so user edits to `.agent-prices.md` win.
+goes through `load_prices()` so user edits to
+`agents/.agent-prices.md` win.
 """
 
 from __future__ import annotations
@@ -24,7 +25,7 @@ from pathlib import Path
 from scripts.ai_council._default_prices import DEFAULT_PRICES, LAST_UPDATED, as_rows
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
-PRICES_FILE = REPO_ROOT / ".agent-prices.md"
+PRICES_FILE = REPO_ROOT / "agents" / ".agent-prices.md"
 
 # Heuristic: 1 token ≈ 4 characters of English text. OpenAI's tiktoken
 # is more accurate but pulls in a heavy dep we explicitly avoid.
@@ -115,14 +116,14 @@ def is_stale(table: PriceTable, now: _dt.datetime | None = None) -> bool:
 
 
 def load_prices(path: Path = PRICES_FILE) -> PriceTable:
-    """Parse `.agent-prices.md`; bootstrap from defaults if missing."""
+    """Parse `agents/.agent-prices.md`; bootstrap from defaults if missing."""
     if not path.exists():
         bootstrap_from_defaults(path)
     return _parse(path.read_text(encoding="utf-8"))
 
 
 def bootstrap_from_defaults(path: Path = PRICES_FILE) -> None:
-    """Write a fresh `.agent-prices.md` from `_default_prices.py`."""
+    """Write a fresh `agents/.agent-prices.md` from `_default_prices.py`."""
     rows = as_rows()
     body = _render_markdown(LAST_UPDATED, "shipped-default", rows)
     path.write_text(body, encoding="utf-8")