@event4u/agent-config 1.15.0 → 1.16.0

package/.agent-src/skills/ai-council/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: ai-council
+description: "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'."
+source: package
+---
+
+# ai-council
+
+## When to use
+
+* The host agent has drafted a roadmap, plan, or design and wants an
+  **external** critique that is not biased by its own framing.
+* The user asks "what would Claude / GPT say about this?" or invokes
+  `/council`.
+* A PR diff or commit range needs a second-opinion review beyond the
+  internal four-judge pass.
+* A free-form proposal benefits from being challenged by an outside
+  reviewer before it calcifies into work.
+
+Do NOT use when:
+
+* The decision is internal-only and budget matters more than diversity
+  of opinion → use `subagent-orchestration` (in-session, no network,
+  no money).
+* The artefact contains secrets that cannot be redacted with the
+  bundler's pattern set → ask the user before sending.
+* The user has not configured any council member → state that and stop;
+  do not silently fall back to anything.
+
+## Goal
+
+Bring in **independent** external models to critique a project
+artefact. Independent means: the council members never see the host
+agent's reasoning, internal state, or framing language — only the
+artefact (roadmap, diff, prompt, file set) plus a neutral system
+prompt that asks them to think on their own merits.
+
+## Neutrality guidelines (Iron Law)
+
+```
+THE COUNCIL DOES NOT SEE THE HOST AGENT'S ANALYSIS.
+THE COUNCIL DOES NOT SEE PRIOR REPLIES.
+THE COUNCIL SEES THE ARTEFACT + THE NEUTRAL SYSTEM PROMPT. NOTHING ELSE.
+```
+
+If you find yourself wanting to "frame" the artefact for the council,
+stop. Framing is exactly what kills the second-opinion value. Use the
+unbiased system prompts in `scripts/ai_council/prompts.py`; do not
+roll your own.
+
+### Neutrality — context-handoff
+
+External reviewers do better critique when they know **what the
+project is**, not just what the artefact looks like. The council
+ships a neutral **handoff preamble** (modelled on `/agent-handoff`)
+in front of every member's system prompt, assembled by
+`prompts.handoff_preamble(project, original_ask)`:
+
+| Carried | Forbidden |
+|---|---|
+| Project name (from `composer.json` / `package.json` / repo dir) | Host-agent identity (Augment, Claude Code, Cursor, Cline, Windsurf, Copilot agent) — stripped line-by-line before send |
+| Stack one-liner inferred from manifest files | Host-agent reasoning, prior turns, internal analysis |
+| One paragraph of repo purpose from `README.md` (max 400 chars) | Host-agent framing language ("I think this looks weak", "the user probably wants…") |
+| The user's **original ask** verbatim (the free-form sentence that triggered `/council`) | Anything the host agent generated about the artefact |
+
+`detect_project_context()` in `scripts/ai_council/project_context.py`
+reads only the manifest files + root README; missing fields collapse
+to `None` and the preamble silently omits the line. With both
+`project=None` and `original_ask=""`, the preamble degrades to the
+bare `NEUTRALITY_PREAMBLE` (v1 shape — back-compat for callers that
+have not migrated yet).
+
+## Execution modes
+
+A council member can run in one of three transports. The neutrality
+preamble is identical across all of them — only the path the bytes
+travel changes.
+
+| Mode | Client | Billable | Transport | Status |
+|---|---|---|---|---|
+| `api` | `AnthropicClient` / `OpenAIClient` | yes | provider SDK + key from `~/.config/agent-config/<provider>.key` | shipped |
+| `manual` | `ManualClient` | no | `stdout` (prompt block) + `stdin` (user pastes the web-UI reply, terminated by a line containing only `END`) | shipped (Phase 2b) |
+| `playwright` | `PlaywrightClient` | no | persistent-profile browser at the provider's chat URL via DOM adapter | reserved (Phase 2c — capture-only) |
+
+Resolution lives in `scripts/ai_council/modes.py`:
+`resolve_mode(name, invocation_mode, member_settings, global_mode)`
+with precedence **invocation flag > per-member setting > global
+setting > default (`api`)**. Whitespace-and-case insensitive; empty
+strings fall through; unknown values raise `InvalidModeError` with
+the offending settings path (`ai_council.mode`,
+`ai_council.members.<name>.mode`, or `/council mode=`).
+
+### Manual-mode UX
+
+`ManualClient` is the user-as-transport variant: the agent prints
+one Markdown block per member (system prompt + handoff preamble +
+artefact between two `═` rules), the user pastes it into a web
+chat (Claude.ai, ChatGPT, Gemini), then pastes the reply back
+ending with a line containing only `END`. After each reply, a 1/2/3
+menu surfaces:
+
+1. More feedback for this member (continue this thread)
+2. Done with this member, move to the next
+3. Abort the council run
+
+`1` re-emits a follow-up block addressed to the **same chat
+thread** (no system prompt repetition). `2` records the round and
+moves to the next member. `3` returns `error="manual_aborted"` for
+that member and the orchestrator stops the fan-out.
+
+### Cost-gate bypass for non-billable members
+
+`ExternalAIClient.billable` is the contract. Clients with
+`billable=False` (today: `ManualClient`; future: `PlaywrightClient`)
+bypass the cost gate entirely — the orchestrator skips the
+projection check, the `on_overrun` callback, and the USD-budget
+short-circuit for that member, but still records the response's
+token counts (from the manual-paste length heuristic or the
+provider's reply, when available) for observability. Mixed runs
+(one manual + one api) gate only the api members.
+
+## Procedure
+
+1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
+   `diff`, `files`) and locate the source. Refuse to proceed if the
+   target is ambiguous.
+2. **Bundle + redact.** Call `scripts/ai_council/bundler.py` to produce
+   a redacted artefact bundle. If `BundleTooLarge` fires, surface the
+   size and ask the user to narrow scope — do NOT truncate silently.
+3. **Confirm spend.** Before any network call, surface members + cost
+   ceiling and require an explicit user `1` to proceed. Autonomy
+   settings do not override this gate.
+4. **Fan out.** Dispatch the bundle to each enabled council member via
+   `scripts/ai_council/orchestrator.py`. Each member receives the
+   neutrality preamble from `prompts.py` plus the artefact — nothing
+   from the host agent's prior reasoning.
+5. **Render results.** Stack each member's response under its own
+   provider-attributed heading. Never merge or paraphrase responses
+   into the host agent's voice.
+6. **Summarise.** Write a `Convergence / Divergence` block listing
+   agreements, disagreements, and unique insights — provider-attributed.
+7. **Translate to options.** Convert actionable council suggestions
+   into concrete numbered options for the user. The user decides;
+   the council advises.
+
+## Output format
+
+Every council reply MUST contain, in this order:
+
+1. **Header line** with mode, member count, and total token cost.
+2. **One section per member**, titled `### <provider> · <model>`,
+   containing the member's verbatim output.
+3. **Convergence / Divergence summary** — bullet list, every claim
+   attributed by provider name.
+4. **User-facing options** — numbered block per `user-interaction`,
+   with "discard council input" always present as an option.
+
+The host agent NEVER ships council output as its own reasoning.
+Provider attribution stays visible in every render.
+
+## Do NOT
+
+- Do NOT paraphrase council output into the host agent's voice — strip
+  attribution and you've stripped the value.
+- Do NOT pre-warm the council with the host agent's analysis or
+  identity — that primes the reviewer and collapses diversity.
+- Do NOT silently truncate a too-large bundle — surface the size and
+  ask for narrower scope.
+- Do NOT auto-spend tokens under `personal.autonomy: on` — the cost
+  gate fires every time, no exceptions.
+- Do NOT reuse SDK clients across invocations — re-load keys via
+  `load_*_key()` each call.
+
+## Gotchas
+
+Real failure modes seen in the wild:
+
+- **Bias-by-framing:** agent pastes "I think X is the right answer,
+  what do you think?" → council rubber-stamps. Symptom: 100%
+  convergence, zero unique insight. Fix: send artefact only, neutral
+  preamble, no host reasoning.
+- **Silent budget overrun:** `cost_budget_exceeded` mid-fan-out, agent
+  retries one member to "complete" the council. Result: skewed sample,
+  hidden spend. Fix: surface partial result, stop, ask user.
+- **Identity leak:** roadmap text contains "the agent decided…" —
+  reviewer infers host model and mirrors it. Fix: redact host-agent
+  identity strings before bundling.
+
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| "Pre-warm" the council with the agent's own analysis. | Bias attack — collapses the reviewer to a yes-man. | Send the artefact text only. |
+| Paste the host-agent identity ("I am Augment / Claude Code…") | Identity primes the reviewer's model. | Neutrality preamble in `prompts.py` already handles this. |
+| Silently truncate a too-large bundle. | Misleads the reviewer into thinking they saw the whole thing. | Bundler raises `BundleTooLarge`; surface and ask for narrower scope. |
+| Reuse the same SDK client across calls without re-loading the key. | Leaks the key in long-lived process state. | Each invocation builds fresh clients from `load_*_key()`. |
+| Auto-spend tokens under `personal.autonomy: on`. | Autonomy ≠ permission to spend money. | Always ask before consultation, even under autonomy. |
+
+## Redaction expectations
+
+The bundler's redaction pass strips:
+
+- Paths matching `~/.config/agent-config/*.key`.
+- Lines starting with `Authorization:`.
+- `key = …`, `secret = …`, `token = …`, `password = …` assignments.
+- `sk-ant-…` and `sk-…` token-like strings.
+
+If your artefact contains other sensitive data (customer names,
+internal hostnames, contractual prose) you are responsible for
+scrubbing it before bundling. The redaction pass is a **floor**, not
+a ceiling.
+
+## Cost awareness
+
+Every consultation hits a paid API. The orchestrator enforces
+per-invocation caps from `ai_council.cost_budget`:
+
+- `max_input_tokens` / `max_output_tokens` — token caps across all members.
+- `max_total_usd` — per-invocation USD ceiling. `0` disables the USD ceiling (token caps still apply).
+- `max_calls` — maximum number of council members per invocation.
+- `daily_limit_usd` — rolling 24h spend cap across all `/council`
+  invocations. `0` disables. Persists in
+  `~/.config/agent-config/council-spend.jsonl` (mode 0600). Breach
+  fires `on_overrun(event)` with `event.breach_kind == "daily"` and,
+  if the callback returns False or is absent, tags the member
+  `daily_budget_exceeded` instead of `cost_budget_exceeded`.
+
+Prices come from `.agent-prices.md` (gitignored, refreshed weekly).
+The pricing module bootstraps it from `_default_prices.py` on first
+use and flags it stale when older than the most recent Monday 00:00
+UTC.
+
+### Pre-call estimate format
+
+Before the cost gate, compute `orchestrator.estimate(question, members,
+table)` and render a per-member table. Heuristic: `len(text) / 4` for
+input, member's `max_tokens` ceiling for output (actual spend is
+usually lower).
+
+> External council call — billable
+>
+> Mode: roadmap · Target: `agents/roadmaps/<name>.md` (~3 KB after redaction)
+>
+> | member                          | est. in / out tokens | est. USD |
+> |---------------------------------|---------------------:|---------:|
+> | anthropic / claude-sonnet-4-5   |      ~750 / 1024     |  $0.0176 |
+> | openai / gpt-4o                 |      ~750 / 1024     |  $0.0121 |
+> | **total**                       |                      | **$0.0297** |
+>
+> Budget: 50k in / 20k out tokens · USD ceiling: $0.50
+>
+> 1. Run the consultation
+> 2. Cancel
+
+### Stale price-table gate
+
+If `pricing.is_stale(table)` returns true, ask before proceeding:
+
+> Price table is stale (last_updated: YYYY-MM-DD)
+> 1. Refresh now (`python3 scripts/update_prices.py`)
+> 2. Continue with the stale table
+> 3. Cancel
+
+Do not silently auto-refresh — the user keeps control.
+
+### Mid-flow overrun callback (`on_overrun`)
+
+The orchestrator runs members **sequentially**. Before each member
+whose projected spend would breach a cap, it invokes the
+`on_overrun(event)` callback. The callback returns `True` to proceed
+with that member (raises the effective ceiling for THIS call only)
+or `False` to skip and record `cost_budget_exceeded`. The callback
+fires again for every subsequent breaching member — the user keeps
+control on each step.
+
+> Cost budget overrun — pausing before next member
+>
+> Member: openai / gpt-4o (member 2 of 2)
+> Already spent: ~620 in / ~480 out tokens · $0.0094
+> Next call estimate: ~750 in / 1024 out tokens · $0.0121
+> **Projected total after this call: $0.0215** (ceiling: $0.0150)
+>
+> 1. Continue with this member
+> 2. Skip this member (records `cost_budget_exceeded`, continues with the rest)
+
+Without `on_overrun`, breaching short-circuits all remaining members
+(v1 fallback). Do not retry silently. Surface the partial result and
+ask the user.
+
+## Multi-round debate (`rounds:N`)
+
+`consult(..., rounds=N)` enables 2-3 round critique loops. Round 1
+runs the standard single-round flow. Round 2+ rebuilds the user
+prompt as `<original artefact> + <prior round, anonymised>` so each
+member can refine, agree, or push back on the previous critique
+without seeing which provider produced which point.
+
+| Property | Behaviour |
+|---|---|
+| Anonymisation | Provider/model identity is stripped. Reviewers are labelled `Reviewer A / B / C…` in input order. |
+| Errored prior responses | Skipped — they reveal nothing useful and can leak provider error formats. |
+| Cost budget | Accumulates across rounds. A round-2 call that breaches the cap fires `on_overrun` exactly like a round-1 breach. |
+| Daily limit | Same — every billable round-2 call records spend in the rolling 24h ledger. |
+| Return value | Final round only. Use `on_round_complete(round_idx, responses)` to capture intermediate rounds for rendering. |
+
+> Iron Law: anonymisation is non-negotiable. If you ever need to
+> surface "which model said what" between rounds, that is a different
+> feature — debug-only, off by default, never enabled in user-facing
+> output. The neutrality contract dies the moment a member learns it
+> is talking to Claude vs GPT in round 2.
+
+Pre-call estimate must surface the round count: total = `N × single-round cost`. Render inline:
+
+```
+External council call — billable · 2 rounds
+Round 1: artefact only
+Round 2: artefact + anonymised round 1 critiques
+
+| member             | per-round | × 2     |
+|--------------------|----------:|--------:|
+| anthropic/sonnet   |   $0.0176 | $0.0352 |
+| openai/gpt-4o      |   $0.0121 | $0.0242 |
+| **total**          |           | $0.0594 |
+```
+
+## See also
+
+- `/council` command — the user-facing entry point.
+- `subagent-orchestration` skill — internal multi-agent variant (no
+  network, no spend, but no diversity of weights either).
+- `scripts/ai_council/prompts.py` — neutrality preamble + per-mode
+  system prompts.
+- `scripts/ai_council/bundler.py` — redaction pattern set + size
+  guard.
+- `docs/customization.md` § `ai_council.*` — settings reference.

package/.agent-src/skills/api-endpoint/SKILL.md

@@ -28,8 +28,8 @@ Do NOT use when:
 
 ### What to generate
 
-1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `.augment/guidelines/php/controllers.md`.
-2. **FormRequest** — Validation rules, `authorize()` via policies. Read `.augment/guidelines/php/validations.md`.
+1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `../../../docs/guidelines/php/controllers.md`.
+2. **FormRequest** — Validation rules, `authorize()` via policies. Read `../../../docs/guidelines/php/validations.md`.
 3. **Resource** — JSON response transformation. Read `agents/docs/api-resources.md`.
 4. **Route** — Add to the correct versioned route file.
 5. **Policy** — If authorization is needed.

package/.agent-src/skills/blade-ui/SKILL.md

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

package/.agent-src/skills/blast-radius-analyzer/SKILL.md

@@ -81,7 +81,7 @@ For every dependency, mark:
 
 ### 5. Consult engineering memory
 
-Via [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
+Via [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
 `retrieve(types=["architecture-decisions", "ownership"],
 keys=<changed paths + changed symbol>, limit=5)`. Surface:
 

package/.agent-src/skills/bug-analyzer/SKILL.md

@@ -84,7 +84,7 @@ Gather all available evidence before forming any hypothesis:
 - Read each file in the call chain to understand the data flow.
 - Check existing context docs (`agents/contexts/`) for the affected area.
 - **Consult engineering memory.** Via
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
   `retrieve(types=["historical-patterns", "incident-learnings"],
   keys=[<error class>, <affected file paths>], limit=3)`. A prior
   matching pattern or incident is the single most reliable accelerator

package/.agent-src/skills/command-routing/SKILL.md

@@ -12,7 +12,7 @@ execution:
 
 ## When to use
 
-Triggered when user invokes a slash command. The `slash-commands` rule (always loaded) handles core behavior — this skill adds context inference and GitHub API patterns.
+Triggered when user invokes a slash command. The `slash-command-routing-policy` rule (always loaded) handles core behavior — this skill adds context inference and GitHub API patterns.
 
 ## Procedure: Execute a command
 

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

@@ -117,7 +117,7 @@ Required sections in this order:
 ### 4. Enforce the size budget
 
 Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
-`guidelines/agent-infra/size-and-scope.md`.
+`docs/guidelines/agent-infra/size-and-scope.md`.
 
 | Category | Target |
 |---|---|

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -66,5 +66,5 @@ Read all PR commits → identify net effect → write single Conventional Commit
 ## References
 
 - Rule: `commit-conventions` — format, types, scope
-- Guideline: `guidelines/php/git.md` — selection rules, anti-patterns, checklist
+- Guideline: `docs/guidelines/php/git.md` — selection rules, anti-patterns, checklist
 - Command: `/commit` — uses this skill

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -57,7 +57,7 @@ Only after this analysis, proceed with optimization.
 **What does NOT belong here:**
 - Coding standards (→ `.augment/rules/` and `.augment/guidelines/`)
 - Architecture principles like SOLID, KISS, DRY (→ `.augment/rules/architecture.md`)
-- PHP conventions (→ `.augment/guidelines/php/`)
+- PHP conventions (→ `../../../docs/guidelines/php/`)
 - Scope control rules (→ `.augment/rules/scope-control.md`)
 - Language/tone rules (→ `.augment/rules/language-and-tone.md`)
 - Detailed module documentation (→ `app/Modules/README.md`)
@@ -115,7 +115,7 @@ both. Instead, reference with a table:
 | What | Where |
 |---|---|
 | PHP coding rules | `.augment/rules/php-coding.md` |
-| Controller guidelines | `.augment/guidelines/php/controllers.md` |
+| Controller guidelines | `../../../docs/guidelines/php/controllers.md` |
 ```
 
 ## Line Budget Enforcement

package/.agent-src/skills/developer-like-execution/SKILL.md

@@ -127,13 +127,13 @@ If important information is missing:
 - Compare with requirements, tickets, current behavior, tests, existing patterns
 - Identify likely cause and smallest correct change
 - **Consult memory — invariants and prior decisions.** Via
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md), call
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md), call
   `retrieve(types=["domain-invariants", "architecture-decisions"], keys=<touched paths>, limit=3)`.
   A matching `domain-invariant` is a hard constraint — violating it =
   regression, surface the conflict before proceeding. A matching
   `architecture-decision` explains *why* the current shape exists; plan
   around it, do not silently overturn it. Cite matching `id`s in the plan.
-  See [`engineering-memory-data-format`](../../guidelines/agent-infra/engineering-memory-data-format.md)
+  See [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
   for the schema.
 
 ### 4. Define expected behavior first

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
 ---
 

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/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/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/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/override-management/SKILL.md

@@ -70,13 +70,13 @@ 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` |
+| `../../../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.

package/.agent-src/skills/readme-reviewer/SKILL.md

@@ -136,7 +136,7 @@ Structure checks:
 - No duplication between README and `/docs/` (drifts over time)
 - Each `/docs/` file linked from README is self-contained (not just a fragment)
 
-→ See `guidelines/docs/readme-size-and-splitting.md` for full thresholds,
+→ See `docs/guidelines/docs/readme-size-and-splitting.md` for full thresholds,
 splitting strategies, anti-patterns.
 
 ## Output format

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

@@ -100,7 +100,7 @@ lines: split deep content to `/docs/` or `references/`. Use `<details>`
 only for secondary, bulky content — never for install, first example, or
 requirements.
 
-→ See `guidelines/docs/readme-size-and-splitting.md` for thresholds,
+→ See `docs/guidelines/docs/readme-size-and-splitting.md` for thresholds,
 splitting strategies (reference-split, deep-link tables, collapsibles),
 multi-audience handling, anti-patterns.