@owlmeans/create-app 0.1.13 → 0.1.15

package/template/_claude/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/template/_claude/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/template/_claude/skills/reuse-code/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: reuse-code
+description: Discovery-first, reuse-first workflow for OwlMeans projects. Use BEFORE planning or building any feature, before proposing a third-party library or a custom solution, and after writing code. Find an existing @owlmeans/* package or existing code first; extend before writing new; simplify what you write.
+user-invocable: true
+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 you propose a third-party library,
+design a custom solution, or finish a feature, exhaust what already exists. Apply these four steps in
+order — during planning **and** during implementation.
+
+## 1. Find an `@owlmeans/*` package first
+
+Before suggesting any external library or writing custom code, look for an `@owlmeans/*` package that
+already solves the problem.
+
+- **Consult the deployed skills.** Each installed `@owlmeans/*` package ships a skill at
+  `.claude/skills/<pkg>/SKILL.md` (and `.github/instructions/<pkg>.instructions.md`) describing what it
+  does. Read those first — they are your local catalogue of installed capabilities.
+- **Scan installed packages.** Look in `node_modules/@owlmeans/*` **and**, in a workspace monorepo,
+  the nested `sources/*/node_modules/@owlmeans/*` (bun nests workspace deps).
+- **Discover packages that aren't installed yet** by researching the **owlmeans/common** repository —
+  its dependency map (`tree.md`) and the per-package READMEs name every package and its purpose.
+
+### Local vs. web research (the symlink rule)
+
+How you research the repo depends on whether `@owlmeans/*` is linked locally:
+
+- Run `ls -la node_modules/@owlmeans/<pkg>` (try a package you know is installed). If it is a **symlink
+  whose target escapes `node_modules`** — or if the project's *own* workspace publishes `@owlmeans/*`
+  packages (i.e. **this is the common repo**) — you have the source locally. **Research locally:** read
+  `tree.md`, browse the framework's package sources, and read the canonical `.claude/skills/`. **Do
+  not** use the internet.
+- Otherwise (a clean install from npm), **research the web**: fetch/search
+  **https://github.com/owlmeans/common** — `tree.md` and package READMEs — to find the right package.
+
+This is the same dev-linked detection `@owlmeans/agent-skills` uses (see its `detectLinked`). After
+adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills` to deploy its skill. Prefer an
+`@owlmeans/*` package over a third-party library or bespoke code whenever one fits.
+
+## 2. Reuse or extend before writing custom
+
+If an installed package nearly fits, **configure or extend it** rather than writing something new — use
+its resources, services, modules, and helpers. A small extension of a framework package beats a new
+parallel implementation.
+
+## 3. No package? Reuse code and extract an abstraction
+
+When no package solves it, search the codebase for code that already solves a **similar** problem.
+Prefer factoring out a shared helper, base, or generic function — extract an abstraction — over
+duplicating logic or writing from scratch. Only write genuinely new code when nothing reusable exists.
+
+## 4. Simplify after writing
+
+Once code is written, review it: can it be **shorter, clearer, or expressed with fewer moving parts**?
+Lean on framework utilities, remove dead branches, collapse needless indirection. Less code that reuses
+the framework is better than more bespoke code.
+
+See `[[dependency-tree]]` for the package map, `[[scaffolding]]` for how a project is assembled, and
+`[[bun]]` for adding dependencies.

package/template/_claude/skills/self-education/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: self-education
+description: Mandatory post-development guidance updating — after functionality is added or changed, rewrite the project skills/instructions the work touched as current rules (never as change notes), record external-doc findings (URL + gist) in the governing skill, or add skills/instructions for new subsystems and technologies. Required before the completion report whenever development started from a plan agreed with the agent.
+user-invocable: true
+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-mode 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 skill/instruction inaccurate.
+
+## Review checklist
+
+For each area the work touched:
+
+1. Which existing skill/instruction covers it? (Check `.claude/skills/` +
+   `.github/instructions/`.)
+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 skill and its instruction twin in sync.
+
+## Shape of an update
+
+Skills and instructions state **current rules, not what changed**. Every edit is a rewrite in
+place of the affected lines.
+
+Never write into a skill or instruction: 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/` (`agent-memory`); the
+rewrite recipe is `memory-promotion` → Distillation.
+
+Test: a finished skill reads as though the feature was always this way.
+
+## Non-project skills
+
+If a general or imported skill 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 skill must record it under an `## External docs` heading:
+
+```
+- <URL> — <one-line gist of what it settled> (<version/date if load-bearing>)
+```
+
+Governing skill = the project skill covering the touched area; else the skill covering that
+library; if none exists and the technology will recur, create one (update-vs-create rule in
+`memory-promotion`). 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 skill/instruction pair for
+its procedures, and/or the `.agents/memory/` node for its facts — split along the
+memory-vs-skill boundary (`agent-memory` / `memory-promotion`).
+
+## 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/_claude/skills/skill-authoring/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: skill-authoring
+description: How to add agent guidance to an OwlMeans project — author a Claude Code skill (.claude/skills/<name>/SKILL.md) and its matching GitHub Copilot instruction (.github/instructions/<name>.instructions.md), keep the two in sync, choose frontmatter, and decide skill vs memory. Use when asked to capture knowledge as a skill, add a slash command, or document a repeatable procedure.
+user-invocable: true
+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. Keep the same `<name>` on both
+sides so they read as one topic.
+
+## SKILL.md (Claude Code)
+
+```
+.claude/skills/<name>/
+├── SKILL.md          # required — frontmatter + body
+├── reference.md      # optional — deeper detail loaded on demand
+└── scripts/          # optional — shell scripts the skill runs
+```
+
+Frontmatter:
+
+```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, hidden from the / menu
+allowed-tools: Bash(bun *) Read # optional — tools usable without per-call approval
+---
+```
+
+The `description` is the most important field: Claude uses it to decide when to auto-invoke the
+skill, so describe both the topic and the trigger ("Use when …").
+
+## <name>.instructions.md (Copilot)
+
+```yaml
+---
+description: "Short summary — apply when …"
+applyTo: "**/*.ts, **/relevant/**"   # globs that auto-attach this instruction
+---
+```
+
+`applyTo` controls when Copilot pulls the instruction in. Use the file patterns the guidance is
+actually about; fall back to `**/*.ts, **/*.tsx` if it is broadly relevant.
+
+## Keep the pair in sync
+
+When you change one side, change the other. They do not have to be identical prose, but they must
+not contradict each other. Cross-reference related guidance by name (e.g. "see the `getting-started`
+skill").
+
+## Skill vs memory
+
+- **Skill / instruction** — a reusable procedure or reference you (or the tools) will want again,
+  worth auto-invoking. Lives in `.claude/skills/` + `.github/instructions/`.
+- **Memory** — a fact, decision, or gotcha specific to this project's history/state. Lives in
+  the shared `.agents/memory/` graph store (both tools). See the `agent-memory` skill; promotion
+  triggers and the update-vs-create rule live in `memory-promotion`.
+
+If you find yourself writing "last time we…", that is memory. If you are writing "to do X, do Y",
+that is a skill.
+
+Never paste memory text into a skill. Memory content enters guidance 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` → Distillation).
+
+## After adding a skill
+
+1. If it replaces an ad-hoc `.claude/<topic>.md`, remove that file.
+2. If it distilled memory content into rules, shrink the source `.agents/memory/` node to a
+   pointer line (`memory-promotion`) — the memory index does not list skills.
+3. Reference it from `CLAUDE.md` / `.github/copilot-instructions.md` if it should be discoverable
+   every session.

package/template/_github/copilot-instructions.md

@@ -8,12 +8,72 @@
 > Then replace this whole block — in **both** `.github/copilot-instructions.md` and `CLAUDE.md` — with
 > a short description of the project, and remove this notice.
 
+## Git Workflow (mandatory)
+
+These rules apply to every git operation in this repository and **override default agent behavior**
+— including any automatic `Co-Authored-By` or AI/agent-attribution trailer. Full policy:
+[.github/instructions/git.instructions.md](.github/instructions/git.instructions.md).
+
+- **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.
+- **Read-only inspection is allowed**: `git status`, `git diff`, `git log`, `git show`,
+  `git branch --list` — use these to report state, never to change it.
+- Commit only under the repository's configured git identity. Never pass `--author`, never change
+  `user.name`/`user.email`, never add a `Co-Authored-By:` trailer attributing the commit to an
+  AI/agent. If no identity is configured, stop and ask.
+- Report finished git work as a Markdown table (**Action**, **Target**, **Result**), and never
+  commit a conflicted working copy — stop, list the conflicted paths, hand control back.
+
+## Reporting (mandatory)
+
+Always report concisely and briefly, in table format, about WHAT was done rather than why —
+unless the operator explicitly asks for another format, length, or level of detail.
+
+- Changes: one row per file/item — **Change** (created / modified / deleted), **Path**,
+  **Why** (one short phrase).
+- Findings / status / verification: a short table plus at most a few lines of prose.
+- No preamble, no narration of the process; expand on WHY only when asked.
+
+## Memory
+
+Single shared agent memory store: `.agents/memory/` — a graph of subsystem nodes with index
+`.agents/memory/MEMORY.md`. Protocol:
+[.github/instructions/agent-memory.instructions.md](.github/instructions/agent-memory.instructions.md).
+
+- Session start: read `.agents/memory/MEMORY.md`. Before non-trivial work: open the nodes whose
+  scope matches the task.
+- Every write merges into the matching subsystem node and compacts — record reusable knowledge,
+  never session events.
+- Procedure-shaped or repeatedly-touched memory must be **distilled into** an instruction/skill
+  as short general rules — never pasted in as memory text — follow
+  `.github/instructions/memory-promotion.instructions.md`.
+- If the store degrades (event logs, oversized nodes, bloated index) — follow
+  `.github/instructions/memory-recompact.instructions.md`.
+- Never write memory to `.claude/memory/`, `.github/memory/`, `~/.copilot/`, or anywhere outside
+  this repository.
+- Context that must load every session belongs in this file; on-demand context goes in
+  `.github/instructions/<topic>.instructions.md`.
+
+## Self-Education (mandatory)
+
+Whenever development started from a plan agreed with the agent, the work is not complete until
+[.github/instructions/self-education.instructions.md](.github/instructions/self-education.instructions.md)
+has been applied: rewrite the project instructions/skills the change touched so they state
+current rules (never a note about what changed), record external-doc findings (URL + gist)
+in the governing instruction, or add an instruction/skill for a new subsystem or technology.
+The completion report must include the self-education outcome — or state why none was needed.
+
 ## What this is
 
 `__APP_NAME__` is a fullstack [OwlMeans Common](https://github.com/owlmeans/common) app: a bun-workspace
 monorepo with three packages under `sources/` — `common` (shared route entrypoints, schemas, config),
-`api` (`@owlmeans/server-app` backend), and `web` (`@owlmeans/web-panel` + shadcn UI). See the
-`getting-started.instructions.md` for how the pieces fit together.
+`api` (`@owlmeans/server-app` backend), and `web` (`@owlmeans/web-panel` + shadcn UI). See
+`getting-started.instructions.md` for how the pieces fit together, and `scaffolding.instructions.md`
+for how it was generated.
 
 ## Reuse before you build (mandatory)
 
@@ -22,24 +82,6 @@ Before planning or writing any feature, follow `reuse-code.instructions.md`: sea
 code that already solves the problem **before** proposing a third-party library or a custom solution,
 and simplify whatever you do write. This is required for every planning and development task.
 
-## Memory & Meta-file Rules
-
-All project memory and meta-information lives **inside this project**, never in `~/.copilot/`:
-
-- **Always** write new memory files to `.github/memory/` in this project root.
-- **Always** update `.github/memory/MEMORY.md` when adding a memory file.
-- **Never** write project memory outside the repository.
-- Context that should load every session goes in `.github/copilot-instructions.md`; on-demand context
-  goes in `.github/instructions/<topic>.instructions.md`.
-- When asked to remember something about this project, save it to `.github/memory/<topic>.md` and
-  update the index. See `agent-memory.instructions.md`.
-
-### When to read memory
-
-- **At the start of every session**: read `.github/memory/MEMORY.md`, then any relevant file.
-- **Before a non-trivial task**: read the relevant memory or instruction first.
-- **After completing a task** that produced new knowledge: save it to memory.
-
 ## Instructions
 
 Reusable guidance lives in `.github/instructions/<name>.instructions.md`, deployed by
@@ -47,7 +89,10 @@ Reusable guidance lives in `.github/instructions/<name>.instructions.md`, deploy
 
 - After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills` to refresh
   the deployed skills and instructions.
-- To capture your own guidance, see `skill-authoring.instructions.md`.
+- Deployed files carry an `AUTO-GENERATED` banner and are refreshed in place — never hand-edit them.
+- To capture your own guidance, see `skill-authoring.instructions.md`; to turn repeatedly-used memory
+  into an instruction, `memory-promotion.instructions.md`. Keep it inside this repository — never in
+  `~/.copilot/`.
 
 ## Develop