@event4u/agent-config 1.15.0 → 1.17.0

package/.agent-src/skills/flux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flux
-description: "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."
+description: "Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives."
 source: package
 ---
 
@@ -8,7 +8,12 @@ source: package
 
 ## Positioning — dispatched, not standalone
 
-`flux` is the **primitive-library executor** for projects on the Livewire + Flux stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+`flux` is the **primitive-library executor** for projects on the
+Livewire + Flux stack. It is invoked by
+[`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
 
 | Concern | Owner |
 |---|---|
@@ -22,8 +27,8 @@ source: package
 
 Cite this skill when:
 
-- Project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
-- Building forms, modals, dropdowns, toasts, or other standard UI elements Flux already provides
+- The project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
+- Building forms, modals, dropdowns, toasts, or other standard UI elements that Flux already provides
 
 Do NOT use when:
 
@@ -64,16 +69,31 @@ Do NOT use when:
 
 ### Review pass — a11y findings + preview envelope
 
-When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
-
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
-
-Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
 
 ## Gotcha
 
-- Model tends to use old Flux API syntax — always check latest docs.
+- The model tends to use old Flux API syntax — always check latest docs.
 - Flux has built-in validation display — don't add manual error rendering alongside it.
 - Don't mix Flux with raw HTML form elements in the same form.
 

package/.agent-src/skills/git-workflow/SKILL.md

@@ -20,7 +20,7 @@ Do NOT use when:
 
 ## Conventions
 
-→ See guideline `guidelines/php/git.md` for branch naming, commit messages, PR conventions.
+→ See guideline `docs/guidelines/php/git.md` for branch naming, commit messages, PR conventions.
 → See `commit-conventions` rule for commit format, types, and scope rules.
 → Use `conventional-commits-writing` skill for generating/reviewing commit messages.
 

package/.agent-src/skills/github-ci/SKILL.md

@@ -14,7 +14,7 @@ Use this skill when working with GitHub Actions workflows, CI pipeline configura
 
 1. Read `.github/workflows/` to understand the full pipeline.
 2. Check `AGENTS.md` for quality tool commands and testing setup.
-3. Read `.augment/commands/fix-ci.md` for CI failure debugging workflow.
+3. Read `commands/fix/ci.md` for CI failure debugging workflow.
 
 ## Workflow overview
 
@@ -91,7 +91,7 @@ Check `.github/workflows/` for the runner types used. Common patterns:
 3. Get logs: `GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs`
 4. Fix locally, verify in container, then push.
 
-See `.augment/commands/fix-ci.md` for the full debugging workflow.
+See `commands/fix/ci.md` for the full debugging workflow.
 
 
 ## Output format

package/.agent-src/skills/guideline-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guideline-writing
-description: "Use when creating or editing a guideline in .agent-src.uncompressed/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'."
+description: "Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'."
 source: package
 ---
 
@@ -10,7 +10,7 @@ source: package
 
 ## When to use
 
-* Creating a new guideline in `.agent-src.uncompressed/guidelines/{topic}/{name}.md`
+* Creating a new guideline in `docs/guidelines/{topic}/{name}.md`
 * Rewriting an existing guideline (not a typo fix)
 * Extracting reference material out of a bloated skill or rule
 * Consolidating repeated explanations from multiple skills
@@ -42,7 +42,7 @@ Creating or materially rewriting a guideline **must** go through Understand
 
 * **Understand** — which skills or rules will cite this guideline? If the
   answer is "none", the guideline has no home — stop.
-* **Research** — **inspect** `guidelines/` for overlap and grep
+* **Research** — **inspect** `docs/guidelines/` for overlap and grep
   `.agent-src.uncompressed/` for pages that already cover the topic.
   **Analyze** 1–2 peer guidelines in the same topic folder for tone.
 * **Draft** — propose location (topic folder + filename) and outline. Only
@@ -50,7 +50,7 @@ Creating or materially rewriting a guideline **must** go through Understand
 
 ### 1. Pick the right topic folder
 
-Folders under `.agent-src.uncompressed/guidelines/`:
+Folders under `docs/guidelines/`:
 
 | Folder | Contents |
 |---|---|
@@ -89,7 +89,7 @@ approval-gated flow as for skills and rules.
 A guideline is useless if nothing cites it. Before closing the task:
 
 * Add a link from at least one skill or rule using the pattern
-  `→ See 'guidelines/{topic}/{name}.md' for full X`.
+  `→ See 'docs/guidelines/{topic}/{name}.md' for full X`.
 * Keep the citing skill/rule **executable** — do not hollow it out into a
   pointer. (Normative source: [`preservation-guard`](../../rules/preservation-guard.md).)
 
@@ -107,16 +107,16 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 
 ### 6. Validate
 
-* Run `python3 scripts/skill_linter.py .agent-src.uncompressed/guidelines/{topic}/{name}.md`
+* Run `python3 scripts/skill_linter.py docs/guidelines/{topic}/{name}.md`
   → 0 FAIL (guidelines have relaxed linting but must still parse).
-* Run `bash scripts/compress.sh --sync` → regenerates `.agent-src/guidelines/`.
+* Run `bash scripts/compress.sh --sync` → projects updates.
 * Run `python3 scripts/check_references.py` → no broken links.
 * Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
   the script list) — must exit 0 except for tolerated warnings.
 
 ## Output format
 
-1. Complete guideline at `.agent-src.uncompressed/guidelines/{topic}/{name}.md`
+1. Complete guideline at `docs/guidelines/{topic}/{name}.md`
 2. At least one skill or rule linking to it
 3. Linter + `check_references.py` clean
 4. `bash scripts/compress.sh --sync` confirmation
@@ -135,7 +135,7 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 * Do NOT add `type:` or `alwaysApply:` to the frontmatter
 * Do NOT embed numbered procedures — those belong in skills
 * Do NOT create an orphan guideline with no inbound links
-* Do NOT edit `.agent-src/guidelines/` or `.augment/guidelines/` — generated
+* Do NOT reintroduce `.agent-src.uncompressed/guidelines/` — relocated to `docs/guidelines/`
 
 ## Cloud Behavior
 
@@ -151,7 +151,7 @@ validation:
 * Self-check the body: reference material, no numbered procedures,
   named in a topic folder.
 * Tell the user to save under
-  `.agent-src.uncompressed/guidelines/{topic}/{name}.md` and run
+  `docs/guidelines/{topic}/{name}.md` and run
   `task sync && task lint-skills && task check-refs` locally before
   committing.
 * Do not call the linter, ref-checker, or compressor — they only
@@ -161,7 +161,7 @@ validation:
 
 Good guideline name + description:
 
-> Path: `guidelines/agent-infra/size-and-scope.md`
+> Path: `docs/guidelines/agent-infra/size-and-scope.md`
 > Description: "Golden size rules for rules, skills, commands, and guidelines"
 
 Bad:

package/.agent-src/skills/judge-code-quality/SKILL.md

@@ -112,8 +112,8 @@ Required fields (ordered):
    a codebase convention; omit only when verdict is `apply`
 
 If a finding needs runtime confirmation (running a formatter, linter,
-or static analyzer), note it as a follow-up for the implementer — the
-judge does not execute tools.
+or static analyzer to see the actual report), note it as a follow-up
+for the implementer — the judge does not execute tools.
 
 ## Gotcha
 
@@ -140,16 +140,15 @@ judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Code-review rubric** — Google Engineering Practices, "The Standard
   of Code Review" and "What to look for in a code review",
   [google.github.io/eng-practices/review/reviewer](https://google.github.io/eng-practices/review/reviewer/).
   The lenses (design, functionality, complexity, tests, naming, comments,
-  style, consistency) the judge applies — codebase conventions over
-  external style preferences.
+  style, consistency) the judge applies — prioritizing codebase conventions
+  over external style preferences.
 - [`subagent-orchestration`](../subagent-orchestration/SKILL.md) —
   model-pairing rules (`subagents.judge_model` one tier above implementer).
 - Sibling judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),

package/.agent-src/skills/judge-security-auditor/SKILL.md

@@ -150,13 +150,12 @@ Runtime boundary: the judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Security rubric** — OWASP Application Security Verification Standard
   (ASVS), [owasp.org/www-project-application-security-verification-standard](https://owasp.org/www-project-application-security-verification-standard/).
-  Finding categories (authentication, access control, validation,
+  The finding categories (authentication, access control, validation,
   cryptography, error handling) the judge walks on every diff.
 - [`subagent-orchestration`](../subagent-orchestration/SKILL.md) —
   model-pairing rules (`subagents.judge_model` one tier above implementer).

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -134,10 +134,9 @@ as a follow-up for the implementer — the judge does not execute tools.
 ## References
 
 - **LLM-as-a-Judge foundations** — Zheng et al., "Judging LLM-as-a-Judge
-  with MT-Bench and Chatbot Arena" (2023),
-  [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
-  Establishes the specialized-judge pattern and failure modes (position
-  bias, self-consistency) this skill defends against.
+  with MT-Bench and Chatbot Arena" (2023), [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685).
+  Establishes the specialized-judge pattern and its known failure modes
+  (position bias, self-consistency) this skill must defend against.
 - **Test-value rubric** — Martin Fowler, "Test Pyramid",
   [martinfowler.com/bliki/TestPyramid.html](https://martinfowler.com/bliki/TestPyramid.html),
   and Kent Beck, "Test Desiderata",

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -119,7 +119,7 @@ Choose one:
 
 A grep that returns zero hits is **not** proof of no overlap. Knowledge in
 this package is distributed across **four surfaces** — `skills/`, `rules/`,
-`guidelines/`, `commands/`. Skip any of them and recall drops to ~25 %.
+`docs/guidelines/`, `commands/`. Skip any of them and recall drops to ~25 %.
 Run all four steps before declaring "no overlap":
 
 **Step 1 — list all four surfaces.** Directory taxonomy is free evidence:
@@ -127,11 +127,11 @@ Run all four steps before declaring "no overlap":
 ```bash
 ls .agent-src.uncompressed/skills/ \
    .agent-src.uncompressed/rules/ \
-   .agent-src.uncompressed/guidelines/ \
+   docs/guidelines/ \
    .agent-src.uncompressed/commands/
 ```
 
-Sub-directories matter — `guidelines/php/patterns/`, `guidelines/agent-infra/`,
+Sub-directories matter — `docs/guidelines/php/patterns/`, `docs/guidelines/agent-infra/`,
 etc. carry topic taxonomies a flat file scan misses. Always descend one level.
 
 **Step 2 — grep with both vocabularies.** Search for **solution-words** *and*
@@ -194,7 +194,7 @@ The output of this skill is a **curated proposal** under
 `.augment/templates/agents/proposal.example.md` (shipped by the
 package). This is the input to the five-stage pipeline
 (capture → classify → propose → gate → upstream); see
-[`self-improvement-pipeline`](../../guidelines/agent-infra/self-improvement-pipeline.md).
+[`self-improvement-pipeline`](../../../docs/guidelines/agent-infra/self-improvement-pipeline.md).
 
 Mandatory fields the draft MUST fill:
 

package/.agent-src/skills/lint-skills/SKILL.md

@@ -17,56 +17,74 @@ execution:
 
 ## When to use
 
-- Validate shape of every skill/rule in `.agent-src.uncompressed/`
-- Verify `execution:` metadata is well-formed
-- Pre-PR local check before CI skill-lint job
-- Investigate reported linter failure
+Use this skill when:
 
-NOT: single file (call `skill_linter.py <path>`), cross-refs (use `check-refs`),
-compression freshness (use `bash scripts/compress.sh --check`).
+- Validating the shape of every skill and rule in `.agent-src.uncompressed/`
+- Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
+- Checking locally before opening a PR that CI's skill-lint job will pass
+- Investigating a reported linter failure on a specific skill or rule
+
+Do NOT use when:
+
+- Linting only one file — call `python3 scripts/skill_linter.py <path>` directly
+- Checking cross-references between files — use `check-refs` instead
+- Checking compression freshness — use `bash scripts/compress.sh --check` instead
 
 ## Procedure
 
-1. **Inspect env** — `python3` on PATH, cwd = agent-config repo root (linter
-   resolves `.agent-src.uncompressed/skills/` relative to cwd).
-2. **Dispatch via runtime** —
+### 1. Inspect the environment
 
-   ```bash
-   python3 scripts/runtime_dispatcher.py run --skill lint-skills
-   ```
+Confirm `python3` is available and the working directory is the agent-config
+repository root — the linter expects to find `.agent-src.uncompressed/skills/`
+and related directories relative to `cwd`.
 
-   Handler runs `python3 scripts/skill_linter.py --all`, captures stdout/stderr,
-   returns typed `ExecutionResult`.
-3. **Verify result** —
-   - `status: success` + `exit_code: 0` → all clean
-   - `exit_code: 1` → warnings only — review stdout
-   - `exit_code: 2` → errors — fix flagged files
-   - `status: timeout` → investigate slowdown, do not just raise timeout
-   - `status: error` → interpreter missing or wrong cwd
+### 2. Dispatch via the runtime layer
 
-## Output
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
 
-1. One-line summary: status, exit code, duration (ms)
-2. Count of skills/rules inspected if known
-3. First 10 errored files: code + message
-4. Next action: fix, re-run, or surface raw stdout
+```bash
+python3 scripts/runtime_dispatcher.py run --skill lint-skills
+```
 
-## Gotcha
+The dispatcher resolves the request, the shell handler runs
+`python3 scripts/skill_linter.py --all`, captures stdout/stderr, and returns
+a typed `ExecutionResult`.
 
-- `--all` walks full tree — several seconds; bump `timeout_seconds` if repo grew
-- Running outside repo root → zero skills inspected, looks green but is a no-op
-- `exit_code: 1` (warnings) does not fail CI — not the same as "clean"
+### 3. Verify the result
 
-## Do NOT
+Check the returned `ExecutionResult`:
+
+- `status: success` and `exit_code: 0` → all skills and rules are clean
+- `exit_code: 1` → warnings only — review `stdout` for the listed warnings
+- `exit_code: 2` → errors present — fix the flagged files before continuing
+- `status: timeout` → the linter exceeded `timeout_seconds` — investigate
+- `status: error` → the interpreter could not launch — check that `python3`
+  is on `PATH` and the repository root is the current working directory
 
-- Do NOT call `skill_linter.py` directly when the intent is to exercise the
-  runtime path — go through the dispatcher
-- Do NOT raise `timeout_seconds` to mask slowdowns
-- Do NOT add pipes/redirection — handler uses `shell=False`, argv form only
+## Output format
 
-## References
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of skills and rules the linter inspected, if known
+3. List of files with errors (first 10), each with code and message
+4. Next action: fix errors, re-run, or surface the raw `stdout` for review
+
+## Gotchas
+
+- The command uses `--all`, which walks the full tree — expect several seconds
+  of runtime on a warm repo; bump `timeout_seconds` if the repo has grown
+- Running outside the agent-config repo root will make the linter report zero
+  skills, which looks like a pass but is actually a no-op
+- Warnings (`exit_code: 1`) do not fail CI by default; do not dismiss them as
+  "green" when the task is to get to zero warnings
+
+## Do NOT
 
-- Skill: `check-refs` — sibling pilot that runs the cross-ref checker
-- Rule: `runtime-safety` — execution metadata constraints
-- Script: `scripts/skill_linter.py`, `scripts/runtime_dispatcher.py`,
-  `scripts/runtime_handler.py`
+- Do NOT invoke `scripts/skill_linter.py` directly when the intent is to test
+  the runtime path — use the dispatcher so the handler and result object are
+  exercised
+- Do NOT raise `timeout_seconds` to hide a genuinely slow linter pass —
+  investigate the slowdown first
+- Do NOT add shell redirection or pipes to `command` — the handler runs
+  `subprocess.run` with `shell=False`; only argv form is supported

package/.agent-src/skills/livewire/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: livewire
-description: "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."
+description: "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."
 source: package
 ---
 

package/.agent-src/skills/md-language-check/SKILL.md

@@ -16,29 +16,32 @@ execution:
 
 ## When to use
 
-Fire **before** saving any `.md` file under:
+Fire this skill **before** writing or saving any `.md` file under:
 
-- `.agent-src.uncompressed/` (source of truth)
+- `.agent-src.uncompressed/` (source of truth — skills, rules, commands, guidelines, templates, contexts)
 - `.agent-src/` (compressed projection)
 - `.augment/` (local agent projection)
-- `agents/` (project roadmaps, contexts, sessions)
+- `agents/` (project-specific roadmaps, contexts, sessions)
 
-Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md`
-files are ALWAYS English" + § Detection heuristic, every `.md` in
-those trees must be English. Bilingual content lives only in labeled
+Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md` files
+are ALWAYS English" and § Detection heuristic, every `.md` file in those
+trees must be English. Bilingual content lives only in labeled
 `DE: … · EN: …` anchor blocks.
 
 Do NOT use when:
 
-- Editing project content outside the trees above
-- Reviewing non-`.md` files (checker rejects them)
+- Editing project content outside the trees listed above (READMEs of
+  consumer projects, application docs that follow a different policy)
+- Reviewing chat history files (`.agent-chat-history` is JSONL, not `.md`)
+- Inspecting non-`.md` files — the checker rejects them with a warning
 
 ## Procedure
 
 ### 1. Identify the file(s) about to be saved
 
-Collect every `.md` path the agent is about to create or modify this
-turn. Multiple files → one invocation.
+Collect the absolute or repo-relative path of every `.md` file the
+agent is about to create or modify in this turn. Multiple files in
+one turn → pass them all to a single invocation.
 
 ### 2. Run the checker
 
@@ -46,58 +49,77 @@ turn. Multiple files → one invocation.
 python3 scripts/check_md_language.py <path> [<path> …] [--format json]
 ```
 
-Exit codes: `0` clean, `1` violations (save **blocked** until fixed
-or suppressed), `3` internal error.
+Exit codes:
+
+- `0` → no German content detected, save proceeds
+- `1` → violations found, save is **blocked** until they are resolved
+  or explicitly suppressed
+- `3` → internal error (unreadable file, decode failure)
 
 ### 3. Resolve findings
 
-| Kind | Cause | Fix |
+For every violation:
+
+| Kind | Likely cause | Fix |
 |---|---|---|
-| `umlaut` | German prose in body | Translate to English |
-| `de_word` | German function word in unquoted prose | Translate; or move into `DE: … · EN: …` block |
+| `umlaut` | German prose leaked into body text | Translate the sentence to English |
+| `de_word` | German function word in unquoted prose | Translate; or move into a `DE: … · EN: …` block if intentional bilingual anchor |
 
-Meta-doc that **must** quote German tokens (e.g. the heuristic in
-`language-and-tone.md` itself) → append
-`<!-- md-language-check: ignore -->` to that single line. Never as a
-wholesale silencer.
+If the line is meta-documentation that **must** quote German tokens
+(e.g. the detection heuristic in `language-and-tone.md` itself),
+append `<!-- md-language-check: ignore -->` at the end of that single
+line — never as a wholesale silencer.
 
 ### 4. Re-run and confirm
 
-After every fix re-run on the same paths. Save proceeds only on `0`.
+After every fix, re-run the checker on the same paths. Save only
+proceeds on exit `0`.
 
 ## Allowed escape hatches
 
-- **Labeled anchor** — lines starting with `DE:` / `- DE:` / `* DE:`
-  (and the same for `EN:`) auto-skipped.
-- **Fenced code blocks** — exempt; shell snippets, JSON fixtures,
-  quoted user input pass through.
-- **Inline code** — backtick spans stripped before scanning.
-- **Per-line marker** — `<!-- md-language-check: ignore -->` on lines
-  that genuinely quote German tokens (rare).
+- **Labeled anchor block** — lines starting with `DE:` / `- DE:` /
+  `* DE:` (and the same for `EN:`) are skipped automatically. Use this
+  for intent-based opt-in / opt-out anchors.
+- **Fenced code blocks** — `\`\`\` … \`\`\`` content is exempt, so
+  shell snippets, JSON fixtures, and quoted user input in code
+  blocks pass through untouched.
+- **Inline code** — backtick spans are stripped before scanning;
+  identifiers like `für_test` inside backticks do not flag.
+- **Per-line marker** — append `<!-- md-language-check: ignore -->`
+  to a line that genuinely needs to quote a German token in body
+  prose (rare; reserved for the rules that document the heuristic).
 
 ## Output format
 
 1. One-line summary: `clean` or `N violation(s) found`
 2. Per violation: `file:line — kind \`match\`` plus the offending line
 3. Next action: translate, move into a `DE:`/`EN:` block, add the
-   per-line ignore marker, or revert
+   per-line ignore marker, or revert the change
 
 ## Gotchas
 
-- `.md` files only; non-`.md` paths emit a warning and skip
-- Word list is short and conservative — clean run is **necessary
-  but not sufficient**; agent owns the final language judgement
-- Frontmatter (`--- … ---`) is exempt
+- The checker scans `.md` files only; passing a non-`.md` path emits a
+  warning and skips it
+- The detection word list is intentionally short and conservative —
+  a clean run is **necessary but not sufficient**; the agent still
+  owns the final language judgement
+- Frontmatter (`--- … ---` at file head) is exempt; descriptions and
+  YAML keys can use international characters where the schema allows
 
 ## Do NOT
 
-- Do NOT silence by deleting trigger words from
-  `scripts/check_md_language.py`; extend the allow-list instead
-- Do NOT use the ignore marker as a generic mute
-- Do NOT skip the gate "because the file is small"
+- Do NOT silence the checker by deleting trigger words from
+  `scripts/check_md_language.py`; extend the allow-list (anchor
+  blocks, ignore marker) instead
+- Do NOT add the ignore marker to body prose just to push a save
+  through; the marker is for meta-documentation that quotes tokens,
+  not a generic mute
+- Do NOT skip the gate "because the file is small" — `language-and-tone`
+  § Detection heuristic applies to every save under the four trees
 
 ## Cloud Behavior
 
-Cloud surfaces (Claude.ai Web, Skills API) ship without the script,
-so this skill is **inert** there — apply the heuristic from
-[`language-and-tone`](../../rules/language-and-tone.md) manually.
+On cloud surfaces (Claude.ai Web, Skills API) the checker script is
+not shipped, so this skill is **inert** — the agent applies the
+heuristic from [`language-and-tone`](../../rules/language-and-tone.md)
+manually before emitting the file.

package/.agent-src/skills/override-management/SKILL.md

@@ -31,11 +31,11 @@ Changes to `.augment/` affect ALL projects. Use overrides instead.
 
 ## Procedure: Create an override
 
-Before creating, understand the original:
+Before creating an override, understand the original:
 
-1. **Read the original** from `.augment/{type}/{name}` — understand purpose and behavior
-2. **Check existing overrides** in `agents/overrides/{type}/` — avoid duplicates
-3. **Identify what needs changing** — only override specific behavior that differs
+1. **Read the original** from `.augment/{type}/{name}` — understand its purpose, structure, and behavior.
+2. **Check for existing overrides** in `agents/overrides/{type}/` — avoid duplicates.
+3. **Identify what needs changing** — only override the specific behavior that differs for this project.
 
 When loading any skill, rule, or command:
 
@@ -69,14 +69,14 @@ Override files **must match the original filename** exactly:
 |---|---|
 | `.augment/rules/php-coding.md` | `agents/overrides/rules/php-coding.md` |
 | `.augment/skills/eloquent/SKILL.md` | `agents/overrides/skills/eloquent.md` |
-| `.augment/commands/feature-plan.md` | `agents/overrides/commands/feature-plan.md` |
-| `.augment/guidelines/php/controllers.md` | `agents/overrides/guidelines/php-controllers.md` |
+| `.augment/commands/feature/plan.md` | `agents/overrides/commands/feature/plan.md` |
+| `../../../docs/guidelines/php/controllers.md` | `agents/overrides/guidelines/php-controllers.md` |
 | `.augment/templates/roadmaps.md` | `agents/overrides/templates/roadmaps.md` |
 
 **Skills** are flattened: the original lives in a directory (`skills/{name}/SKILL.md`),
 but the override is a single file (`skills/{name}.md`).
 
-**Guidelines** are flattened with a prefix: `guidelines/php/controllers.md` → `guidelines/php-controllers.md`.
+**Guidelines** are flattened with a prefix: `docs/guidelines/php/controllers.md` → `guidelines/php-controllers.md`.
 
 **Templates** keep their original filename: `templates/roadmaps.md` → `templates/roadmaps.md`.
 

package/.agent-src/skills/php-coder/SKILL.md

@@ -54,7 +54,7 @@ Trigger keywords in the task or surrounding code:
 - allowlist constants: `private const SUPPORTED_FOO = [Type::A, Type::B]`
 
 → Run the sniff test in
-[`guidelines/php/patterns/strategy.md`](../../guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+[`docs/guidelines/php/patterns/strategy.md`](../../../docs/guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
 Two "yes" answers → propose Strategy + Registry **before** adding the new
 branch. Three "yes" → it is already overdue and the refactor is the change.
 

package/.agent-src/skills/playwright-testing/SKILL.md

@@ -16,12 +16,12 @@ Use this skill when:
 - Debugging flaky E2E tests
 - Configuring Playwright for CI/CD
 
-**Guideline:** `.augment/guidelines/e2e/playwright.md` — full conventions, config templates, CI setup.
+**Guideline:** `../../../docs/guidelines/e2e/playwright.md` — full conventions, config templates, CI setup.
 **Rule:** `.augment/rules/e2e-testing.md` — constraints enforced during E2E test work.
 
 ## Procedure: Write Playwright tests
 
-1. **Read the guideline** — `.augment/guidelines/e2e/playwright.md` for detailed conventions.
+1. **Read the guideline** — `../../../docs/guidelines/e2e/playwright.md` for detailed conventions.
 2. **Check Playwright config** — `playwright.config.ts` for browsers, base URL, timeouts.
 3. **Check existing tests** — match patterns in `tests/e2e/` or `e2e/`.
 4. **Check test utilities** — look for page objects, fixtures, helpers.