@owlmeans/create-app 0.1.13 → 0.1.15

package/template/_github/instructions/agent-memory.instructions.md

@@ -0,0 +1,143 @@
+---
+description: "Shared agent memory protocol for the .agents/memory/ graph store (single store for Copilot and Claude Code) — MEMORY.md index, subsystem nodes, compact-on-write, size caps, read protocol. Apply when reading or writing project memory, or when any legacy .claude/memory or .github/memory path appears."
+applyTo: "**/.agents/memory/**, **/.claude/memory/**, **/.github/memory/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Agent memory (`.agents/memory/`)
+
+One shared memory store per repository, used by **both** GitHub Copilot and Claude Code: 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.
+
+Never write memory to `.claude/memory/`, `.github/memory/`, `~/.copilot/`, `~/.claude/`, or
+anywhere outside the repository. Legacy `.claude/memory/` / `.github/memory/` stores are
+retired — if one exists, flag it for migration
+(`.github/instructions/memory-recompact.instructions.md`) instead of writing there.
+
+## Store layout
+
+```
+.agents/memory/
+├── MEMORY.md     # graph root: the only always-read file
+└── <node>.md     # one file per subsystem / concern / integration
+```
+
+Flat directory — graph structure lives in scopes and wiki-links, not subdirectories.
+
+## Node naming
+
+Node id = lowercase-kebab name of the **project-structure part** the knowledge attaches to:
+
+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).
+
+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.
+
+## Index format (`MEMORY.md`)
+
+```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
+   (`.github/instructions/memory-promotion.instructions.md`, else the skill-authoring guidance).
+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 instruction
+
+Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") becomes an
+instruction/skill — follow `.github/instructions/memory-promotion.instructions.md` where present,
+otherwise the skill-authoring guidance. 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 an instruction. "Record the
+rule, not the story" and the size caps above bind instruction bodies at least as tightly as they
+bind nodes (memory-promotion instruction → Distillation).

package/template/_github/instructions/getting-started.instructions.md

@@ -0,0 +1,62 @@
+---
+description: "How to build a fullstack OwlMeans Common app — the common/api/web three-workspace pattern, server and web context bootstrap, shared entrypoints + elevate(), and a session-scoped in-memory resource via @owlmeans/static-resource. Apply when starting a new OwlMeans project or wiring web↔api."
+applyTo: "**/modules.ts, **/context.ts, **/config.ts, **/render.tsx, **/index.tsx, **/sources/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Building a fullstack OwlMeans Common app
+
+A minimal app is a **bun-workspace monorepo with three packages**:
+
+- `sources/common` — shared **entrypoints** (routes), AJV schemas, types and config. The single
+  source of truth.
+- `sources/api` — `@owlmeans/server-app` backend; handlers attached to the shared entrypoints.
+- `sources/web` — `@owlmeans/web-panel` + shadcn UI; screens attached to the same entrypoints.
+
+Full walkthrough: `docs/getting-started.md`. To generate it: `npm create @owlmeans/app`.
+
+## One contract, two sides
+
+Declare each route once in `common`, then `elevate()` it on both sides:
+
+```ts
+// common/modules.ts
+export const sessionModules = [
+  entrypoint(route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
+    filter(params(SessionParamsSchema))),
+]
+// api/modules.ts   → elevate(sessionModules, session.list, handlers.list)
+// web/modules.ts   → elevate(modules, session.list)  // call-only; screens via handler(Component)
+```
+
+## Config
+
+`common/config.ts` registers both services; `base: 'api'` prefixes API routes with `/api`:
+
+```ts
+const cfg = service({ type: AppType.Frontend, service: APP_WEB, host: 'localhost', port: 3001 })
+service({ type: AppType.Backend, service: APP_API, host: 'localhost', port: 3000, base: 'api' }, cfg)
+```
+
+## Backend + in-memory data
+
+```ts
+const context = makeContext(cfg, true)
+appendStaticResource(context, SESSION_ITEMS)   // @owlmeans/static-resource — no DB
+```
+
+Handlers (`handleRequest`/`handleBody`/`handleParams`) use `ctx.getStaticResource<T>(alias)`.
+`static-resource.list()` accepts no criteria — list all and filter in JS. `main(context, appModules)`
+starts the server. Swap for `@owlmeans/mongo-resource` / `redis-resource` when you need persistence.
+
+## Web (shadcn)
+
+`web-panel`'s `PanelApp` is shadcn/Tailwind v4. The app **provides** `@/lib/utils` and
+`@/components/ui/{alert,button,card,input,label,progress}` at the `@` alias (→ `src`). Render with
+`provide` from `@owlmeans/web-client`: `basicRender(<PanelApp context={context} provide={provide} />)`.
+A parent `BASE` route renders the layout via `handler(Layout)`; `HOME` is its default child. Screens
+call the API with `context.entrypoint(alias).call({ params, body })`.
+
+This shape is auth-free by design; add `@owlmeans/server-auth` + `@owlmeans/client-auth` and
+`guard(...)` when needed.

package/template/_github/instructions/git.instructions.md

@@ -0,0 +1,52 @@
+---
+description: "Mandatory git rules — never run state-changing git without explicit instruction, commit only under the user's configured identity (never as the AI/agent, no Co-Authored-By trailer), report finished git work as a Markdown table, and never commit a conflicted working copy. Consult before any git operation."
+applyTo: "**"
+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/template/_github/instructions/memory-promotion.instructions.md

@@ -0,0 +1,111 @@
+---
+description: "Promote procedure-shaped or hot memory into skills/instructions — triggers (procedure test, promote? flags, over-cap), the mandatory distillation rewrite, update-vs-create rule, post-promotion pointer state. Apply when converting memory content into guidance files or when a promote? flag appears in a memory node."
+applyTo: "**/.agents/memory/**, **/.claude/skills/**, **/.github/instructions/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Memory promotion
+
+Memory holds **facts**; **procedures** belong in instructions/skills, where they auto-apply 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 an instruction 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
+instruction.
+
+## Distillation (mandatory)
+
+**Never paste memory text into an instruction.** A promoted line leaves the node as prose about a
+past occurrence and enters the instruction 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 instruction, 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.
+
+An instruction 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.instructions.md`) binds instruction 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 instruction/skill 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 instruction needed memory read/write more than once (a
+  re-encountered ` → promote?` flag);
+- (c) an external technology required internet docs and has no governing instruction.
+
+New instructions multiply lookup cost — compactness applies to the guidance population *and* to
+each instruction'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 instruction exists to prevent.
+3. Author or extend the `.github/instructions/<name>.instructions.md` and its
+   `.claude/skills/<name>/SKILL.md` twin, following the repo's skill-authoring / 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/template/_github/instructions/memory-recompact.instructions.md

@@ -0,0 +1,73 @@
+---
+description: "Whole-store memory recompaction and migration for .agents/memory/ — rebuild node map from project structure, merge records, enforce caps, regenerate the index, fold in and delete legacy .claude/memory and .github/memory stores. Apply when restructuring a memory store or migrating legacy stores."
+applyTo: "**/.agents/memory/**, **/.claude/memory/**, **/.github/memory/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Memory recompaction
+
+Whole-store maintenance for `.agents/memory/` (protocol:
+`.github/instructions/agent-memory.instructions.md`). 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
+   `.github/instructions/memory-promotion.instructions.md`. 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/template/_github/instructions/reuse-code.instructions.md

@@ -0,0 +1,50 @@
+---
+description: "Discovery-first, reuse-first workflow for OwlMeans projects. Apply before planning or building any feature, before proposing a third-party library or custom solution, and after writing code: find an existing @owlmeans/* package or existing code first, extend before writing new, and simplify what you write."
+applyTo: "**/*.ts, **/*.tsx, **/package.json"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Reuse before you build
+
+OwlMeans ships a large framework of `@owlmeans/*` packages. Before proposing a third-party library,
+designing a custom solution, or finishing a feature, exhaust what already exists. Apply these four
+steps in order — during planning **and** implementation.
+
+## 1. Find an `@owlmeans/*` package first
+
+- **Consult the deployed instructions.** Each installed `@owlmeans/*` package ships
+  `.github/instructions/<pkg>.instructions.md` (and `.claude/skills/<pkg>/SKILL.md`) describing what it
+  does — your local catalogue of installed capabilities.
+- **Scan installed packages** in `node_modules/@owlmeans/*` and, in a workspace, the nested
+  `sources/*/node_modules/@owlmeans/*`.
+- **Discover not-yet-installed packages** by researching the **owlmeans/common** repository — its
+  `tree.md` dependency map and per-package READMEs.
+
+### Local vs. web research (the symlink rule)
+
+- `ls -la node_modules/@owlmeans/<pkg>`: a **symlink escaping `node_modules`** — or a project whose own
+  workspace publishes `@owlmeans/*` packages (**this is the common repo**) — means the source is local.
+  **Research locally** (`tree.md`, the package sources, the canonical instructions); do **not** use the
+  internet.
+- Otherwise (clean npm install), **research the web**: https://github.com/owlmeans/common.
+
+After adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills` to deploy its instruction.
+Prefer an `@owlmeans/*` package over a third-party library or bespoke code.
+
+## 2. Reuse or extend before writing custom
+
+If an installed package nearly fits, configure or extend it (its resources, services, modules, helpers)
+rather than writing a parallel implementation.
+
+## 3. No package? Reuse code and extract an abstraction
+
+Search the codebase for code solving a **similar** problem. Factor out a shared helper or abstraction
+instead of duplicating or starting from scratch. Write new code only when nothing reusable exists.
+
+## 4. Simplify after writing
+
+Review new code: can it be shorter, clearer, fewer moving parts? Lean on framework utilities, drop dead
+branches. Less code that reuses the framework beats more bespoke code.
+
+See the `dependency-tree`, `scaffolding`, and `bun` instructions.

package/template/_github/instructions/self-education.instructions.md

@@ -0,0 +1,85 @@
+---
+description: "Mandatory post-development skill/instruction updating — after adding or changing functionality, rewrite touched project guidance as current rules (never as change notes), note external-doc findings in the governing instruction, or add instructions for new subsystems/technologies; required before the completion report when development started from an agreed plan. Apply when editing skills or instruction files after development."
+applyTo: "**/.claude/skills/**, **/.github/instructions/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Self-education
+
+After functionality is added or changed, the guidance that describes it must catch up — the agent
+teaches itself for next time. This pass runs after implementation and verification, **before**
+the completion report.
+
+## When (mandatory)
+
+Development "started from planning" when the session produced a plan the operator approved before
+implementation — a plan approval, an agreed written plan/spec, or an explicit "go ahead" on a
+proposed approach. **Approval of a plan is simultaneously approval of its implicit final step:
+this self-education pass.** A planned task is not finishable without it. If guidance files cannot
+be edited (read-only run), list the required updates in the report instead.
+
+Also recommended after any unplanned change that made an existing instruction/skill inaccurate.
+
+## Review checklist
+
+For each area the work touched:
+
+1. Which existing instruction/skill covers it? (Check `.github/instructions/` +
+   `.claude/skills/`.)
+2. Do its commands, paths, APIs, and behavior claims still hold after the change?
+3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
+   note about what this change did. Keep the instruction and its skill twin in sync.
+
+## Shape of an update
+
+Instructions and skills state **current rules, not what changed**. Every edit is a rewrite in
+place of the affected lines.
+
+Never write into an instruction or skill: dated bulletins ("2026-07-05 — …"), phase or migration
+status ("Phase 3 complete", "migration done", "landed"), "formerly X, now Y", incident
+narratives, fixed-bug logs, or point-in-time inventories. If a line only makes sense to someone
+who watched the change happen, it does not belong in guidance — the rule it taught does, stated
+timelessly. Facts too specific to generalize go to `.agents/memory/`
+(`.github/instructions/agent-memory.instructions.md`); the rewrite recipe is
+`.github/instructions/memory-promotion.instructions.md` → Distillation.
+
+Test: a finished instruction reads as though the feature was always this way.
+
+## Non-project instructions
+
+If a general or imported instruction gained an important usage pattern during the work, add the
+pattern to the **deployed copy** in this repo and note it in the report as an upstream
+candidate — canonical archive copies change only on explicit operator request.
+
+## External docs
+
+If the work required reading internet documentation for an external API, library, or service,
+the governing instruction must record it under an `## External docs` heading:
+
+```
+- <URL> — <one-line gist of what it settled> (<version/date if load-bearing>)
+```
+
+Governing instruction = the project instruction covering the touched area; else the one covering
+that library; if none exists and the technology will recur, create one (update-vs-create rule in
+`.github/instructions/memory-promotion.instructions.md`). Never leave doc findings only in
+memory or the conversation.
+
+## New subsystems / technologies
+
+When new technology or a new subsystem entered the repo: create the instruction/skill pair for
+its procedures, and/or the `.agents/memory/` node for its facts — split along the
+memory-vs-instruction boundary (`.github/instructions/agent-memory.instructions.md` /
+`.github/instructions/memory-promotion.instructions.md`).
+
+## Completion gate
+
+The completion report must contain a Self-education table:
+
+| Item | Action | Path |
+|---|---|---|
+| <area/skill> | updated / created / none-needed | <path> |
+
+"none-needed" requires a one-phrase reason. A post-plan completion report without this table is
+a protocol violation.

package/template/_github/instructions/skill-authoring.instructions.md

@@ -0,0 +1,66 @@
+---
+description: "How to add agent guidance to an OwlMeans project — author a Claude Code skill (.claude/skills/<name>/SKILL.md) and the matching Copilot instruction (.github/instructions/<name>.instructions.md), keep them in sync, and choose skill vs memory. Apply when capturing knowledge as a skill or instruction."
+applyTo: "**/.claude/skills/**, **/.github/instructions/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Authoring agent guidance (skills + instructions)
+
+OwlMeans projects carry agent guidance in two parallel places so both Claude Code and GitHub
+Copilot can use it:
+
+| Tool | Location | Shape |
+|---|---|---|
+| Claude Code | `.claude/skills/<name>/SKILL.md` | one directory per skill, `SKILL.md` is the entrypoint |
+| GitHub Copilot | `.github/instructions/<name>.instructions.md` | one file per topic |
+
+Author **both** for any guidance you want available to either tool, using the same `<name>` on both
+sides so they read as one topic.
+
+## SKILL.md frontmatter (Claude Code)
+
+```yaml
+---
+name: my-skill                  # the /slash-command (lowercase, hyphens)
+description: What it does and WHEN to use it.  # primary auto-invocation signal
+user-invocable: true            # false = background knowledge only
+allowed-tools: Bash(bun *) Read # optional
+---
+```
+
+The `description` decides when Claude auto-invokes the skill — describe the topic and the trigger.
+
+## Instruction frontmatter (Copilot)
+
+```yaml
+---
+description: "Short summary — apply when …"
+applyTo: "**/*.ts, **/relevant/**"   # globs that auto-attach this instruction
+---
+```
+
+`applyTo` controls when Copilot attaches the instruction. Use the patterns the guidance is about;
+fall back to `**/*.ts, **/*.tsx` if broadly relevant.
+
+## Keep the pair in sync
+
+Change one side, change the other. They need not be identical prose but must not contradict.
+Cross-reference related guidance by name.
+
+## Skill vs memory
+
+- **Skill / instruction** — a reusable procedure or reference worth auto-invoking.
+- **Memory** (shared `.agents/memory/` graph store, both tools) — a fact, decision, or gotcha
+  specific to this project's history. See the agent-memory instruction; promotion triggers live
+  in the memory-promotion instruction.
+
+Never paste memory text into guidance. Memory content enters an instruction or skill only as a
+restated general rule — trigger, step, and the failure it prevents, with dates, phase/status
+markers, versions and incident narrative stripped (memory-promotion instruction → Distillation).
+
+## After adding a skill
+
+If it distilled memory content into rules, shrink the source `.agents/memory/` node to a pointer line
+(memory-promotion instruction) — the memory index does not list skills. Reference it from
+`.github/copilot-instructions.md` / `CLAUDE.md` if it should be discoverable every session.

package/template/_claude/memory/MEMORY.md

@@ -1,11 +0,0 @@
-# Memory Index
-
-Read this at the start of every session. Load any file relevant to the current task before acting.
-
-When you learn something durable about __APP_NAME__ that isn't obvious from the code or git history —
-a decision and why, a gotcha, project state or goals — save it to `.claude/memory/<topic>.md` and add
-a one-line pointer below. See the `agent-memory` skill.
-
-## Memory files
-
-_(none yet)_