@owlmeans/create-app 0.1.15 → 0.1.16

package/template/{_claude → _agents}/skills/self-education/SKILL.md

@@ -1,8 +1,9 @@
 ---
 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.
+description: Mandatory post-development guidance updating — after functionality is added or changed, rewrite the project skills the work touched as current rules (never as change notes), record external-doc findings (URL + gist) in the governing skill, or add skills 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
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
@@ -20,24 +21,23 @@ a proposed approach. **Approval of a plan is simultaneously approval of its impl
 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.
+Also recommended after any unplanned change that made an existing skill inaccurate.
 
 ## Review checklist
 
 For each area the work touched:
 
-1. Which existing skill/instruction covers it? (Check `.claude/skills/` +
-   `.github/instructions/`.)
+1. Which existing skill covers it? (Check `.agents/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 skill and its instruction twin in sync.
+   note about what this change did.
 
 ## Shape of an update
 
-Skills and instructions state **current rules, not what changed**. Every edit is a rewrite in
+A skill states **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
+Never write into a 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
@@ -67,8 +67,8 @@ library; if none exists and the technology will recur, create one (update-vs-cre
 
 ## 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
+When new technology or a new subsystem entered the repo: create the skill 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

package/template/_agents/skills/skill-authoring/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: skill-authoring
+description: How to add agent guidance to an OwlMeans project — author one skill at .agents/skills/<name>/SKILL.md that every agent reads, choose frontmatter that validates across Claude Code, Copilot and Codex, refresh the Claude Code symlinks, 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
+metadata:
+  scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Authoring agent guidance (skills)
+
+OwlMeans projects carry agent guidance in two places, and only two:
+
+| What | Where | Loaded |
+|---|---|---|
+| Always-on project context | `AGENTS.md` at the repo root | every session |
+| Topic guidance | `.agents/skills/<name>/SKILL.md` | on demand, by topic or `/<name>` |
+
+`.agents/skills/` is the [Agent Skills](https://agentskills.io) standard location: GitHub Copilot
+and Codex discover it natively. Claude Code reads skills only from `.claude/skills/`, so each skill
+is bridged there by a generated symlink — see "Refresh the Claude Code links" below. **Write a skill
+once; never author a per-agent copy** (`.github/instructions/*.instructions.md`,
+`.github/copilot-instructions.md`, or a real file under `.claude/skills/`).
+
+## Skill layout
+
+```
+.agents/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                  # REQUIRED, must equal the directory name (lowercase, hyphens, ≤64 chars)
+description: What it does and WHEN to use it.   # REQUIRED, ≤1024 chars — the auto-invocation signal
+user-invocable: true            # false = background knowledge only, hidden from the / menu
+allowed-tools: Bash(bun *) Read # optional — space-separated; tools usable without per-call approval
+metadata:                       # optional — anything non-standard goes here
+  scope: general
+---
+```
+
+The `description` is the most important field: every agent uses it to decide when to load the
+skill, so state both the topic and the trigger ("Use when …"). Keep it under 1024 characters —
+Copilot rejects longer ones.
+
+Only the fields above (plus `license` and `compatibility`) are portable. Anything else — including
+this monorepo's `scope: general` routing marker — belongs under `metadata:`, so a skill stays valid
+in every agent that reads it. Claude Code additionally understands `disable-model-invocation`,
+`argument-hint` and `context: fork`; use them only when the skill genuinely needs them.
+
+## Refresh the Claude Code links
+
+After creating, renaming, or deleting a skill, run:
+
+```sh
+sh .agents/scripts/link-skills.sh
+```
+
+It creates `.claude/skills/<name>` → `../../.agents/skills/<name>` for every skill and prunes links
+whose skill is gone. The links are gitignored and are recreated at session start, but a skill added
+mid-session is invisible to Claude Code until the script runs.
+
+## Skill vs memory
+
+- **Skill** — a reusable procedure or reference you (or the agents) will want again, worth loading
+  automatically. Lives in `.agents/skills/`.
+- **Memory** — a fact, decision, or gotcha specific to this project's history/state. Lives in the
+  shared `.agents/memory/` graph store. 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 `.agents/<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 `AGENTS.md` if it should be discoverable every session.
+4. Run `sh .agents/scripts/link-skills.sh`.

package/template/_claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PROJECT_DIR:-.}\"/.agents/scripts/link-skills.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/_gitignore

@@ -5,3 +5,7 @@ dist
 .DS_Store
 bun.lock
 bun.lockb
+
+# Generated Claude Code skill symlinks (canonical skills live in .agents/skills/)
+.claude/skills/*
+!.claude/skills/.gitkeep

package/template/_claude/skills/skill-authoring/SKILL.md

@@ -1,84 +0,0 @@
----
-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/instructions/agent-memory.instructions.md

@@ -1,143 +0,0 @@
----
-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

@@ -1,62 +0,0 @@
----
-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

@@ -1,52 +0,0 @@
----
-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

@@ -1,111 +0,0 @@
----
-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)
-```