@owlmeans/agent-skills 0.1.12 → 0.1.15

package/agent-meta/manifest.json

@@ -1,10 +1,24 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/agent-skills",
-  "version": "0.1.12",
-  "generatedAt": "2026-06-17T14:51:24.131Z",
+  "version": "0.1.15",
+  "generatedAt": "2026-08-07T17:06:32.899Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
+    {
+      "kind": "skill",
+      "name": "self-education",
+      "category": "general",
+      "file": "skills/self-education/SKILL.md",
+      "canonicalPath": ".claude/skills/self-education/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "router-plugins",
+      "category": "general",
+      "file": "skills/router-plugins/SKILL.md",
+      "canonicalPath": ".claude/skills/router-plugins/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "getting-started",
@@ -19,6 +33,20 @@
       "file": "skills/shadcn-web/SKILL.md",
       "canonicalPath": ".claude/skills/shadcn-web/SKILL.md"
     },
+    {
+      "kind": "skill",
+      "name": "memory-recompact",
+      "category": "general",
+      "file": "skills/memory-recompact/SKILL.md",
+      "canonicalPath": ".claude/skills/memory-recompact/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "git",
+      "category": "general",
+      "file": "skills/git/SKILL.md",
+      "canonicalPath": ".claude/skills/git/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "agent-memory",
@@ -47,6 +75,13 @@
       "file": "skills/skill-authoring/SKILL.md",
       "canonicalPath": ".claude/skills/skill-authoring/SKILL.md"
     },
+    {
+      "kind": "skill",
+      "name": "memory-promotion",
+      "category": "general",
+      "file": "skills/memory-promotion/SKILL.md",
+      "canonicalPath": ".claude/skills/memory-promotion/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "shadcn-versions",
@@ -68,6 +103,20 @@
       "file": "instructions/getting-started.instructions.md",
       "canonicalPath": ".github/instructions/getting-started.instructions.md"
     },
+    {
+      "kind": "instruction",
+      "name": "self-education",
+      "category": "general",
+      "file": "instructions/self-education.instructions.md",
+      "canonicalPath": ".github/instructions/self-education.instructions.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "memory-recompact",
+      "category": "general",
+      "file": "instructions/memory-recompact.instructions.md",
+      "canonicalPath": ".github/instructions/memory-recompact.instructions.md"
+    },
     {
       "kind": "instruction",
       "name": "scaffolding",
@@ -82,6 +131,13 @@
       "file": "instructions/skill-authoring.instructions.md",
       "canonicalPath": ".github/instructions/skill-authoring.instructions.md"
     },
+    {
+      "kind": "instruction",
+      "name": "router-plugins",
+      "category": "general",
+      "file": "instructions/router-plugins.instructions.md",
+      "canonicalPath": ".github/instructions/router-plugins.instructions.md"
+    },
     {
       "kind": "instruction",
       "name": "shadcn-versions",
@@ -89,6 +145,13 @@
       "file": "instructions/shadcn-versions.instructions.md",
       "canonicalPath": ".github/instructions/shadcn-versions.instructions.md"
     },
+    {
+      "kind": "instruction",
+      "name": "memory-promotion",
+      "category": "general",
+      "file": "instructions/memory-promotion.instructions.md",
+      "canonicalPath": ".github/instructions/memory-promotion.instructions.md"
+    },
     {
       "kind": "instruction",
       "name": "agent-memory",
@@ -102,6 +165,13 @@
       "category": "general",
       "file": "instructions/shadcn-web.instructions.md",
       "canonicalPath": ".github/instructions/shadcn-web.instructions.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "git",
+      "category": "general",
+      "file": "instructions/git.instructions.md",
+      "canonicalPath": ".github/instructions/git.instructions.md"
     }
   ]
 }

package/agent-meta/skills/agent-memory/SKILL.md

@@ -1,52 +1,142 @@
 ---
 name: agent-memory
-description: How project memory works in an OwlMeans app — where to store facts/decisions/gotchas for Claude Code (.claude/memory/) and Copilot (.github/memory/), the MEMORY.md index, and when to read and write memory. Use when asked to remember something about the project, or to decide where a note belongs.
+description: Shared agent memory protocol — the .agents/memory/ graph store used by both Claude Code and GitHub Copilot: MEMORY.md index, subsystem nodes, compact-on-write merging, size caps, and the read protocol. Use when reading or writing project memory, when asked to remember something, or to decide where knowledge belongs.
 user-invocable: true
 scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
-# Project memory
+# Agent memory (`.agents/memory/`)
 
-Memory is how durable, project-specific knowledge survives across sessions. Keep it **inside the
-project**, never in `~/.claude/` or `~/.copilot/`.
+One shared memory store per repository, used by **both** Claude Code and GitHub Copilot: a graph
+of subsystem nodes rooted in the `MEMORY.md` index. Compactness is the core value — every write
+merges and compacts; nothing is ever appended as a log.
 
-| Tool | Memory dir | Index |
-|---|---|---|
-| Claude Code | `.claude/memory/` | `.claude/memory/MEMORY.md` |
-| GitHub Copilot | `.github/memory/` | `.github/memory/MEMORY.md` |
+Never write memory to `.claude/memory/`, `.github/memory/`, `~/.claude/`, `~/.copilot/`, or
+anywhere outside the repository. Legacy `.claude/memory/` / `.github/memory/` stores are
+retired — if one exists, flag it for `memory-recompact` migration instead of writing there.
 
-Each memory is one Markdown file holding one fact, decision, or gotcha. The `MEMORY.md` index has a
-one-line pointer per file (`- [Title](file.md) — hook`) and is loaded every session, so it must stay
-current.
+## Store layout
 
-## When to read memory
+```
+.agents/memory/
+├── MEMORY.md     # graph root: the only always-read file
+└── <node>.md     # one file per subsystem / concern / integration
+```
 
-- **At the start of every session** — read `MEMORY.md`, then open any file relevant to the task.
-- **Before a non-trivial task** — check for a memory file on that topic and read it first.
-- Don't rely on assumptions when a memory file exists; read it.
+Flat directory — graph structure lives in scopes and wiki-links, not subdirectories.
 
-## When to write memory
+## Node naming
 
-After a task produces knowledge that isn't obvious from the code or git history:
+Node id = lowercase-kebab name of the **project-structure part** the knowledge attaches to:
 
-- A **decision** and why it was made (and what was rejected).
-- A **gotcha** or sharp edge discovered the hard way.
-- **Project state / goals** not derivable from the repo.
+1. **Subsystem** — workspace dir / package name: `manager-web`, `auth`, `vslots`. Deepest
+   unambiguous segment; prefix with the parent only on collision.
+2. **Cross-cutting concern** spanning subsystems: `build`, `testing`, `deploy`, `routing`, `i18n`.
+3. **Integration** — external service/library: `stripe`, `cloudflare`, `openrouter`.
+4. **`workspace`** — repo-level facts that fit nowhere else (remotes, branch topology, env model).
 
-Do **not** record what the code or git history already says, or what only matters to the current
-conversation.
+File is `<node>.md`; the id is the wiki-link target: `[[manager-web]]`. **Never** key a node to an
+event, date, phase, investigation, or task name.
 
-## How to write one
+## Index format (`MEMORY.md`)
 
-1. Create `.claude/memory/<topic>.md` (and the Copilot copy under `.github/memory/`) with a short
-   slug name and a one-line description.
-2. Write the single fact; for decisions/gotchas, add why it matters and how to apply it.
-3. Add a one-line pointer to the matching `MEMORY.md` index.
-4. Before saving, check for an existing file that already covers it — update that instead of
-   duplicating. Delete memories that turn out to be wrong.
+```markdown
+# Memory Graph — <project>
+
+Shared agent memory (`agent-memory` protocol). Read this file at session start.
+Before non-trivial work, open every node whose scope matches the task's files or topics.
+
+## Subsystems
+- [[manager-web]] `sources/manager-web/**` — i18n 8-domain split; owl-theme wiring
+## Cross-cutting
+- [[build]] `**/tsconfig*.json` — tsbuildinfo path pinning; tolerant library builds
+## Integrations
+- [[stripe]] `ext:stripe` — sandbox topology; webhook fan-out
+```
+
+Rules: exactly one line per node — `- [[<node>]] ` + backticked scope + ` — <hook>`; hook ≤ 100
+chars; no dates; only non-empty groups; file ≤ 50 lines; no skills listed (skills self-describe).
+The scope column is the router: match the task's paths/topics against scopes to decide which
+nodes to open.
+
+## Node format
+
+Frontmatter — exactly three fields:
+
+```yaml
+---
+node: vslots                 # = filename without .md; = wiki-link target
+scope: "scripts/vslots/**"   # repo-relative globs; ext:<service> for integrations; . for workspace
+updated: 2026-08             # month granularity only
+---
+```
+
+Body — only non-empty sections, in this order:
+
+- `## Facts` — what IS: structure, behavior, topology. 1–3 lines each.
+- `## Invariants` — what MUST HOLD; optionally "broke when violated: <symptom>".
+- `## Gotchas` — symptom → cause → counter-move, ≤ 3 lines each.
+- `## Pointers` — key files, promoted-skill pointer lines, `External docs` (URL + gist).
+- `## Status` — optional; in-flight state only; every line dated; prune resolved lines on every read.
+
+`Status` is the **only** place dates and unfinished-work notes are allowed. Link related nodes
+inline with `[[node]]`.
+
+## Read protocol
+
+- **Session start**: read `.agents/memory/MEMORY.md` — the index only.
+- **Before a non-trivial task**: open every node whose scope matches the task (typically 1–3).
+- **When a topic surfaces mid-session** that the index names: open its node before acting.
+- **Never bulk-read** the store — the index + scopes exist so you don't have to.
+
+## Write protocol (compact-on-write)
+
+Every write is a merge, never an append:
+
+1. **Extract** — reduce the outcome to reusable knowledge atoms (rule below). Nothing survives →
+   write nothing.
+2. **Locate** — match scopes to find the node; none matches → create one per the naming rule and
+   add its index line.
+3. **Merge / supersede** — place each atom in the right section; if it refines or contradicts an
+   existing line, **rewrite that line in place** — never append a dated correction. The node
+   always reads as current truth.
+4. **Compact** — reread the node; collapse redundancy; delete anything the code or git history
+   now states; prune resolved `Status` lines.
+5. **Cap** — over soft cap: compact harder. Over hard cap: split by sub-scope into a linked child
+   node, or promote procedure-shaped overflow (`memory-promotion` where present, else
+   `skill-authoring`).
+6. **Index** — update the hook line if the node's center of gravity moved; bump `updated:`.
+
+## Knowledge, not events
+
+**Record the rule, not the story.** For every line ask: *what must a future agent know to act
+correctly, stated without reference to this session?* Keep invariants, cause→effect,
+counter-moves, recognition fingerprints (symptoms). Drop dates, phase numbers, who did what,
+attempt sequences, and anything recoverable from code or git.
+
+Before (event log): "Verification 2026-06-11 … Bug found: script missing embedded-count logic.
+Fix deployed to all copies; second run idempotent."
+After (knowledge): "`nested-agent-context.sh` exists as byte-identical copies in the archive and
+each repo — fan every fix out to all copies; verify with `diff`. Correct re-runs are no-ops."
+
+## Size caps (hard)
+
+| Thing | Cap |
+|---|---|
+| Index entry | 1 line, hook ≤ 100 chars |
+| `MEMORY.md` | ≤ 50 lines |
+| Node file (soft / hard) | 80 / 120 lines |
+| Single fact/gotcha | ≤ 3 lines |
+| `Status` section | ≤ 5 dated lines |
+| Nodes per store (soft) | ~25 — merge low-traffic siblings beyond |
 
 ## Memory vs skill
 
-If you are writing a **repeatable procedure** ("to do X, do Y"), that is a skill — see the
-`skill-authoring` skill. Memory is for **facts about this project** ("we chose X because Y").
+Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") becomes a skill —
+follow `memory-promotion` where present, otherwise `skill-authoring`. Repeated use of a node to
+*perform* tasks, and over-cap nodes full of steps, are promotion triggers.
+
+Promotion is a **rewrite, never a move**: never paste node text into a skill. "Record the rule,
+not the story" and the size caps above bind skill bodies at least as tightly as they bind nodes
+(`memory-promotion` → Distillation).

package/agent-meta/skills/git/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: git
+description: "Git workflow policy — never run state-changing git without an explicit instruction, commit only under the repository's configured identity (no AI-attribution trailer), report finished git work as a Markdown table, never commit a conflicted working copy. Use before any git operation."
+user-invocable: false
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Git Workflow Rules
+
+**Mandatory and universal.** These rules apply to every git operation in this repository and
+**override any default agent behavior** — including any automatic `Co-Authored-By` or
+AI/agent-attribution trailer. Consult them before running any git command.
+
+## 0. Never run state-changing git without explicit instruction
+
+- **Never run state-changing git operations** (`commit`, `add`/`rm` staging, `push`,
+  `reset`/rollback, `revert`, `rebase`, `merge`, `branch`, `checkout`/`switch`, `stash`,
+  `tag`, `cherry-pick`, force-push, etc.) unless the user **explicitly instructs it in the
+  current request**. Permission to make code edits is **not** permission to touch git.
+- **Only exception**: creating and operating inside a **temporary git worktree** that a task
+  or subagent has **explicitly requested** for that purpose. Outside such an explicitly
+  requested tmp worktree, do nothing with git.
+- **Read-only inspection is allowed**: `git status`, `git diff`, `git log`, `git show`,
+  `git branch --list`, etc. — use these to report state, never to change it.
+
+## 1. Never commit under the agent's identity
+
+- Commit only under the repository's preconfigured git identity — whatever `git config user.name`
+  and `git config user.email` resolve to (set by the user, globally or locally).
+- **Never** override authorship: do not pass `--author`, do not set or change `user.name` /
+  `user.email`, and never substitute an AI / agent / assistant name or email.
+- **Never** add a `Co-Authored-By:` trailer (or any other trailer) attributing the commit to
+  Claude, Copilot, or any AI/agent. Every commit is the user's, attributed solely to the user.
+- If the repository has no git identity configured (neither local nor global), stop and ask the
+  user — do not invent one.
+
+## 2. Always report finished git work as a table
+
+- After completing any git action (commit, push, branch, checkout, merge, rebase, stash, tag,
+  reset, etc.), summarize what was done as a Markdown table.
+- One row per action. Include at least **Action**, **Target** (branch / remote / files / ref),
+  and **Result** (commit SHA, `pushed`, `up to date`, `conflict`, …). Add a **Notes** column
+  when useful.
+
+## 3. Never commit a conflicted working copy
+
+- If a `merge`, `rebase`, `cherry-pick`, `stash pop`/`apply`, or `pull` produces conflicts,
+  **do not** finalize it: do not run `git commit`, `git merge --continue`,
+  `git rebase --continue`, or stage-and-commit the conflicted tree to "resolve" it on the
+  user's behalf.
+- Stop, list the conflicted paths in the report table, and hand control back to the user —
+  unless the user has explicitly told you how to resolve the conflict and commit.

package/agent-meta/skills/memory-promotion/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: memory-promotion
+description: Transform procedure-shaped or repeatedly-used memory into skills and instructions — the procedure-shape test, the mandatory distillation rewrite, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, when writing memory-derived content into a skill, or during recompaction.
+user-invocable: true
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Memory promotion
+
+Memory holds **facts**; **procedures** belong in skills/instructions, where they auto-invoke and
+stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
+teaches itself.
+
+Promotion is a **rewrite, never a move**. Memory text pasted into a skill is the single most
+common way this harness degrades — see Distillation below.
+
+## Triggers
+
+- **Procedure shape**: the content answers *how to do X* — ordered steps, imperative verbs,
+  command lines, if-this-do-that tables. Promote it.
+- **Repeated touch**: an existing ` → promote?` flag on content you are touching again means
+  promote now; if mid-task, promotion becomes the first row of the completion report.
+- **Over-cap**: a node past the 120-line hard cap with roughly a third or more procedure-shaped
+  content → promote the procedures instead of splitting the node.
+- Corroborating only (weak — agents don't commit, so only user commits appear):
+  `git log --oneline -- .agents/memory/<node>.md` showing ≥ 3 commits within ~a month marks a
+  hot node worth evaluating.
+
+## Procedure-shape test
+
+Procedure-shaped answers *how to do X*: ordered steps, imperative verbs, commands, action tables.
+Fact-shaped answers *what is true*: declarative structure, invariants, symptom→cause pairs.
+Mixed entries split — the fact stays in the node, the "then do" is distilled into a rule in the
+skill.
+
+## Distillation (mandatory)
+
+**Never paste memory text into a skill.** A promoted line leaves the node as prose about a past
+occurrence and enters the skill as **one general rule**: *when this applies → do this → or this
+breaks*, stated so it holds next time rather than describing last time.
+
+| Strip | Keep |
+|---|---|
+| dates, phase/status markers, "COMPLETE", "landed" | the condition that makes the rule apply |
+| versions, image tags, SHAs — unless the rule turns on the version | the step to take |
+| "was X, now Y", "the former X was removed" | the failure it prevents |
+| who did it, attempt sequences, incident narrative | the recognition fingerprint (symptom) |
+| point-in-time inventories, counts, snapshots | |
+
+Before (memory): "2026-07-05 — the control-board git card was removed; the dialog now owns all
+git actions."
+After (rule): "Git actions live in the git dialog; the control board holds none."
+
+Before (memory): "Phase 3 (COMPLETE, 2026-06-13): added the init-container build, publisher
+`src/build.ts`, kephemeral v0.1.5."
+After (rule): "Production images build in an init container driven by `publisher/src/build.ts`."
+
+**If the rule cannot be stated without saying when it happened, it is not promotable** — it stays
+a memory fact, or it is dropped.
+
+### Budget
+
+A promotion normally adds **1–5 lines** to an existing skill, and a single rule is ≤ 3 lines. A
+whole new section, or more text added than the node lost, means the content was moved rather than
+distilled — redo it.
+
+A skill may legitimately run long when it maps a large subsystem, so length alone is not the test:
+**every line must be a rule, a contract, or a pointer.** A section that reads as the story of how
+the code got there is pollution at any length. "Record the rule, not the story" (`agent-memory`)
+binds skill bodies at least as tightly as it binds nodes.
+
+## Flagging (how content earns promotion)
+
+When you **merge** procedure-shaped content into a node, or you **use** (not merely check) a
+node's content to perform a task, append ` → promote?` to that line or section heading.
+Evaluable by reading the file alone — no tooling required.
+
+## Update vs create
+
+**Default is update** — extend the existing skill/instruction whose scope covers the activity,
+even partially; keep both twins in sync. Create a NEW pair only when:
+
+- (a) a new subsystem or technology entered the repo;
+- (b) an activity with no covering skill needed memory read/write more than once (a
+  re-encountered ` → promote?` flag);
+- (c) an external technology required internet docs and has no governing skill.
+
+New skills multiply lookup cost — compactness applies to the skill population *and* to each
+skill's body.
+
+## Procedure
+
+1. Collect the flagged / procedure-shaped memory lines.
+2. **Distill** each into a general rule (section above). Not optional — skipping it is the
+   failure mode this skill exists to prevent.
+3. Author or extend the SKILL.md and its `.github/instructions/<name>.instructions.md` twin,
+   following the repo's `skill-authoring` or `create-skill` conventions. Where an existing rule
+   already covers the ground, **rewrite that rule in place**; append only when nothing covers it.
+4. Shrink the node: delete the source lines; leave one pointer line (format below).
+5. Remove the ` → promote?` flags.
+6. Update the node's index hook if its main value moved; bump `updated:`.
+7. Report per the Reporting rule.
+
+## Post-promotion state
+
+The node keeps exactly one line under `## Pointers`:
+
+```
+- <activity> → skill `<name>` (procedure lives in .claude/skills/<name>/ + .github/instructions/<name>.instructions.md)
+```

package/agent-meta/skills/memory-recompact/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: memory-recompact
+description: Recompact or migrate a whole .agents/memory/ store — rebuild the node map from project structure, merge event-shaped records into subsystem nodes, deduplicate, enforce caps, regenerate the MEMORY.md index, and fold in legacy .claude/memory and .github/memory stores. Use when a store degrades into event logs, indexes bloat or conflict, or for one-time migration.
+disable-model-invocation: true
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Memory recompaction
+
+Whole-store maintenance for `.agents/memory/` (protocol: `agent-memory`). Also the migration
+procedure for legacy `.claude/memory/` + `.github/memory/` stores. Store-wide rewrite — propose
+it when triggers appear; the operator invokes it.
+
+## When
+
+- An index entry runs longer than one line, or the index exceeds 50 lines.
+- Nodes keyed by event/date/phase/task, or bodies reading as session narratives.
+- The same fact stated in two or more nodes.
+- More than ~20% of a node is stale `Status` content.
+- A node's `updated:` is months behind commits touching its scope.
+- Legacy `.claude/memory/` or `.github/memory/` dirs exist → run the migration below.
+
+## Build the target node map first
+
+Before reading any record bodies, derive the node set from **project structure**: workspaces
+array / top-level dirs → subsystem nodes; then the cross-cutting concerns and external
+integrations actually present. Write the map down (old file/section → target node). Every
+existing record must land in exactly one node — or split into atoms landing in several. Only
+then process records.
+
+## Per-record pass
+
+For each old file or section:
+
+1. Apply the `agent-memory` extraction rule — keep invariants, cause→effect, counter-moves,
+   symptom fingerprints; drop narratives, dates, attempt logs, anything code/git already states.
+2. Route each surviving atom to its node's section (Facts / Invariants / Gotchas / Pointers;
+   genuinely in-flight state → `Status`, dated).
+3. On conflict between records, the version consistent with **current code** wins — check the
+   code, don't average.
+4. Procedure-shaped survivors do not enter nodes — route them to `memory-promotion`. Routing
+   means distilling them into general rules, never handing the text over verbatim.
+
+## Legacy-store merge (migration)
+
+1. Union `.claude/memory/` and `.github/memory/`. Same-named files are two drifted sources of
+   ONE node — merge both; the code-consistent version wins.
+2. Index-only entries with no backing file: extract the fact into its node, or drop if stale.
+3. Old `## Skills` / "Key Files" index sections are dropped — skills self-describe; harness
+   layout belongs to `CLAUDE.md` / `.github/copilot-instructions.md`. Move genuinely non-obvious
+   dispatch hints there.
+4. When the new store verifies (below), delete both legacy dirs entirely.
+
+## Regenerate the index
+
+Rebuild `MEMORY.md` from the resulting nodes per the `agent-memory` format — never edit the old
+index incrementally.
+
+## Verify
+
+- Every node file is listed in the index; every listed node exists; every wiki-link resolves.
+- All caps met (index ≤ 50 lines; nodes ≤ 120; entries ≤ 3 lines; Status ≤ 5 dated lines).
+- No dates outside `Status` and `updated:`; no event-keyed filenames.
+- Both root instruction files' Memory sections point at `.agents/memory/`.
+- Legacy dirs gone; `grep -rn '\.claude/memory\|\.github/memory'` over the repo's harness files
+  returns nothing but allowlisted historical mentions.
+
+## Report
+
+One table: **Node** | **Sources merged** | **Lines before → after**. Follow the Reporting rule
+(what, not why).

package/agent-meta/skills/router-plugins/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: router-plugins
+description: How OwlMeans UI routing plugins work — the RouterPlugin contract, cascade selection, choosing/switching the router at context provisioning (default OwlMeans vs opt-in react-router), and authoring a new plugin (e.g. SSR). Read before wiring routing in an app or writing a routing plugin.
+scope: general
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# OwlMeans routing plugins
+
+OwlMeans UI routing is pluggable. The core `@owlmeans/router` package is a **host**: it defines the
+`RouterService` facade and holds a registry of `RouterPlugin`s, selecting the active one by
+**cascade**. Route *descriptions* are react-router-compatible (same path placeholders: static,
+`:param`, nested, index) so the same route trees work across plugins.
+
+## Plugins that ship today
+
+| Plugin | Package | Registration | Priority |
+|--------|---------|--------------|----------|
+| OwlMeans in-browser (default) | `@owlmeans/web-router` | `appendWebRouter(ctx)` | 0 |
+| react-router v7 (opt-in) | `@owlmeans/web-router-react-router` | `appendReactRouter(ctx)` | 100 |
+| Native (RN) | `@owlmeans/native-router` | native app wiring | — |
+| SSR | *(future)* | higher-priority `match: env => env.ssr` | >0 |
+
+## Choosing the router at context provisioning
+
+`@owlmeans/web-client` (and `web-panel`) call `appendWebRouter` by default, so **OwlMeans routing is
+the default**. To switch a specific app to react-router, add the opt-in plugin in your `makeContext`
+— its higher priority wins the cascade:
+
+```typescript
+import { makeContext as makeBase } from '@owlmeans/web-panel'
+import { appendReactRouter } from '@owlmeans/web-router-react-router'
+
+export const makeContext = (cfg) => {
+  const context = makeBase(cfg)
+  appendReactRouter(context)   // now react-router handles routing instead of OwlMeans
+  return context
+}
+```
+
+You no longer pass a `provide`/`createBrowserRouter` prop to `<App>`/`<PanelApp>` — routing resolves
+its compiler from the active plugin (`context.router().compile`). The former `provide` export from
+`@owlmeans/web-client` is now a deprecated `undefined` kept only for source compatibility.
+
+## The RouterPlugin contract
+
+```typescript
+interface RouterPlugin {
+  alias: string
+  priority?: number                                   // higher wins; default 0
+  mode?: string                                        // 'browser' | 'ssr' | …
+  match?: (env: RouterEnv, ctx?) => boolean            // undefined ⇒ always applies
+  compile: (routes: RouteObject[], ctx?) => LibraryRouter | Promise<LibraryRouter>
+  provider: () => ComponentType<{ router }>            // renders the compiled router
+  outlet: () => ComponentType                          // renders the next nested match
+  useParams; useLocation; useNavigate; useSearchParams // hooks backed by the plugin
+}
+```
+
+- `RouteObject` is the neutral IR (`{ index?, path?, children?, Component? }`), produced by
+  `@owlmeans/client` from the entrypoint tree — the same objects both plugins consume.
+- `RouterEnv` (`{ hasWindow, ssr, request? }`) drives selection. The browser plugin matches always;
+  an SSR plugin would register at a higher priority with `match: env => env.ssr`.
+
+## Authoring a plugin (e.g. SSR)
+
+1. Implement `RouterPlugin` (reuse the pure matcher from `@owlmeans/router`: `flattenRoutes`,
+   `rankRouteBranches`, `matchRoutes` — they are DOM-free and SSR-safe).
+2. Expose `appendMyRouter(ctx)` = `ensureRouterService(ctx).registerPlugin(makeMyPlugin())`.
+3. Set `priority` above the default (0) and a `match` that fires only in your environment.
+4. Keep the `RouterService` facade methods assignable (native-safety invariant).
+
+## Related
+
+- [[router]] (host + matcher) · [[web-router]] (default browser plugin)
+- `@owlmeans/web-router-react-router` (react-router plugin)