@owlmeans/create-app 0.1.18-rc.8 → 0.1.18

package/template/README.bare.md

@@ -0,0 +1,70 @@
+# __APP_NAME__
+
+__APP_DESCRIPTION__
+
+A fullstack [OwlMeans Common](https://github.com/owlmeans/common) app, scaffolded with
+[`@owlmeans/create-app`](https://www.npmjs.com/package/@owlmeans/create-app) as a bare shell —
+the wiring is complete and there is no example code to delete.
+
+## Workspaces
+
+```
+sources/
+├── common/   # shared entrypoints (routes) and config — used by api AND web
+├── api/      # @owlmeans/server-app backend
+└── web/      # @owlmeans/web-panel + shadcn UI: navigation, layout and screens
+```
+
+## Develop
+
+```sh
+bun install
+bun run dev
+```
+
+- API: http://localhost:3000
+- Web: http://localhost:3001
+
+> **Note:** The API runs over plain HTTP in dev (`cfg.security = { unsecure: true }` in
+> `sources/common/src/config.ts`). If you edit `sources/common`, restart `bun run dev` to
+> rebuild it before the API and web pick up the changes.
+
+## Logging
+
+Log through `@owlmeans/log` (`const log = logger('<scope>')`), never `console.*`. The level is set
+per environment, not in code:
+
+| Runtime | Variables | Default |
+|---|---|---|
+| api (`sources/api/src/config.ts`) | `LOG_LEVEL`, `LOG_DEBUG` | `info` |
+| web (`sources/web/src/config.ts`, build time) | `VITE_LOG_LEVEL`, `VITE_LOG_DEBUG` | `debug` under `vite`, `info` in a build |
+
+`*_DEBUG` lists scopes forced to debug (`*` for all). Local values go in `sources/api/.env` /
+`sources/web/.env` (git-ignored).
+
+## Adding your first feature
+
+1. **`sources/common/src/entrypoints.ts`** — declare the route as an OwlMeans *entrypoint* and
+   give it an AJV filter. Both sides import this one declaration; neither re-declares the route.
+2. **`sources/api`** — register a resource in `src/context.ts` (widening `Context` in
+   `src/types.ts`), then `bind()` the entrypoint with a handler in `src/entrypoints.ts`.
+3. **`sources/web`** — add a screen under `src/screens`, hang it off a frontend route in
+   `src/entrypoints.ts`, list it in `src/nav.ts`, and call the backend with
+   `context.entrypoint(protocol).call({ params, body })`.
+
+See the [OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/docs/getting-started.md)
+for a worked example of all three steps.
+
+## Agent guidance
+
+This project ships agent context in `AGENTS.md`, with skills in
+`.agents/skills/` and a shared memory store at `.agents/memory/`.
+
+Files carrying an `AUTO-GENERATED` banner are managed by
+[`@owlmeans/agent-skills`](https://www.npmjs.com/package/@owlmeans/agent-skills) — don't hand-edit
+them; write your own guidance as separate, un-bannered files. Refresh after adding or upgrading
+`@owlmeans/*` packages:
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18
+```

package/template/README.md

@@ -1,65 +1,14 @@
 # __APP_NAME__
 
-A minimal fullstack [OwlMeans Common](https://github.com/owlmeans/common) app, scaffolded with
-[`@owlmeans/create-app`](https://www.npmjs.com/package/@owlmeans/create-app).
+__APP_DESCRIPTION__
 
-No authentication; session data lives in an **in-memory static resource** on the backend.
+An OwlMeans application has shared protocol declarations in `sources/common`, server bindings in
+`sources/api`, and browser bindings/screens in `sources/web`. Contracts, request schemas, guards
+and gates are declared once in common; runtime packages bind them without changing the declaration.
 
-## Workspaces
+Use `bun run build` from the project root to build every workspace.
 
-```
-sources/
-├── common/   # shared entrypoints (routes), schemas and types — used by api AND web
-├── api/      # @owlmeans/server-app backend; session items in @owlmeans/static-resource
-└── web/      # @owlmeans/web-panel + shadcn UI: navigation, layout and screens
-```
-
-## Develop
-
-```sh
-bun install
-bun run dev
-```
-
-- API: http://localhost:3000
-- Web: http://localhost:3001
-
-Open the **Session** page and add/remove items — they are stored per browser session
-(a `sid` kept in `localStorage`) in an in-memory resource on the API. Restarting the API
-clears them; opening a different browser/incognito window gets an isolated session.
-
-> **Note:** The API runs over plain HTTP in dev (`cfg.security = { unsecure: true }` in
-> `sources/common/src/config.ts`). If you edit `sources/common`, restart `bun run dev` to
-> rebuild it before the API and web pick up the changes.
-
-## How it fits together
-
-1. **`sources/common`** declares the API routes as OwlMeans *entrypoints* (`session.list`,
-   `session.add`, `session.remove`) plus their AJV schemas and shared types.
-2. **`sources/api`** registers a `@owlmeans/static-resource` in its context and `elevate()`s
-   each entrypoint with a handler that does CRUD against it, keyed by the session id.
-3. **`sources/web`** `elevate()`s the same entrypoints to screen components and calls them with
-   `context.entrypoint(alias).call({ params, body })`.
-
-See [OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/docs/getting-started.md)
-for a full walkthrough and the manual (non-scaffolded) version of this project.
-
-## Agent guidance
-
-This project ships agent context in `CLAUDE.md` and `.github/copilot-instructions.md`. Both carry the
-same four mandatory sections a real OwlMeans monorepo uses — **Git Workflow**, **Reporting**,
-**Memory**, **Self-Education** — plus a project-purpose placeholder the agent fills in on its first
-session.
-
-Project memory is a single shared graph store at `.agents/memory/` (index `MEMORY.md`), used by both
-Claude Code and Copilot — never write memory anywhere else.
-
-Reusable guidance lives in `.claude/skills/` (Claude Code) and `.github/instructions/` (Copilot).
-Files carrying an `AUTO-GENERATED` banner are managed by
-[`@owlmeans/agent-skills`](https://www.npmjs.com/package/@owlmeans/agent-skills) — don't hand-edit
-them; write your own guidance as separate, un-bannered files. Refresh after adding or upgrading
-`@owlmeans/*` packages:
-
-```sh
-npx @owlmeans/agent-skills
-```
+Logging goes through `@owlmeans/log`. The api's level comes from `LOG_LEVEL` (default `info`) and
+`LOG_DEBUG` (scopes forced to debug, `*` for all); the web build's from `VITE_LOG_LEVEL` (default
+`debug` under `vite`, `info` in a build) and `VITE_LOG_DEBUG`. Put local values in
+`sources/api/.env` / `sources/web/.env` (git-ignored).

package/template/_agents/scripts/link-skills.sh

@@ -1,12 +1,16 @@
 #!/bin/sh
 # link-skills.sh
 #
-# Bridge the canonical skill store (.agents/skills/) into .claude/skills/ for
-# Claude Code, which discovers skills only under .claude/skills/.  Copilot and
-# Codex read .agents/skills/ natively and need nothing from this script.
+# Bridge every skill an agent should see into the two places agents look:
 #
-# Each skill becomes its own symlink — Claude Code supports per-skill symlink
-# entries, but not a symlinked skills directory.
+#   1. LOCAL   .agents/skills/<name>          -> .claude/skills/<name>
+#   2. LINKED  <upstream>/.agents/skills/<n>  -> .agents/linked-skills/<n>
+#                                            -> .claude/skills/<n>
+#
+# Copilot and Codex read .agents/skills/ and .agents/linked-skills/ natively;
+# Claude Code discovers skills only under .claude/skills/, so both passes land
+# there too.  Each skill becomes its own symlink — Claude Code supports
+# per-skill symlink entries, but not a symlinked skills directory.
 #
 # USAGE
 #   sh .agents/scripts/link-skills.sh
@@ -14,28 +18,63 @@
 # BEHAVIOUR
 #   - creates .claude/skills/<name> -> ../../.agents/skills/<name> for every
 #     .agents/skills/<name>/SKILL.md
-#   - prunes symlinks that dangle or no longer have a SKILL.md behind them
+#   - resolves the upstream repos this one depends on from the root
+#     package.json workspace entries of the form "libraries/<dep>/packages/...",
+#     recursing into each upstream's own package.json (visited list, depth cap
+#     of 4).  A repo that declares no libraries/* workspace entries falls back
+#     to the layout a standalone npm consumer gets: the generated
+#     agent-meta/skills/<name> copies that ship inside the installed @owlmeans
+#     packages.  That fallback scans node_modules/@owlmeans at the project root
+#     AND in every directory up to two levels below it (sources/api/node_modules
+#     and the like), because a workspace package keeps its own node_modules
+#     whenever the linker does not hoist its dependencies to the root.  It never
+#     descends into a node_modules tree, skips any directory whose real path
+#     leaves the root (a projects/<repo> or libraries/<repo> symlink is another
+#     checkout, not this project), and records each physical package once, keyed
+#     by resolved path, so a package reachable through several workspaces
+#     contributes its skills a single time.
+#   - links every upstream skill that no local skill shadows into BOTH
+#     .agents/linked-skills/<name> and .claude/skills/<name>, pointing at the
+#     upstream's real directory using a relative target (never another symlink).
+#     Relative targets survive a hostPath checkout mounted under another root.
+#     A local skill
+#     always wins; a nearer dependency wins over a farther one.
+#   - writes .agents/linked-skills/INDEX.md — skill / origin repo / description
+#     in deterministic order — and rewrites it only when its content changes
+#   - prunes symlinks in both directories that dangle or no longer have a
+#     SKILL.md behind them, and removes .agents/linked-skills/ entirely when
+#     the repo has no upstream skills
 #   - never touches real directories or files (warns instead), never removes
 #     .gitkeep, and always exits 0 so it can run as a SessionStart hook
 #
 # The committed .claude/settings.json runs this at SessionStart.  Run it by
 # hand after creating, renaming, or deleting a skill mid-session.
+#
+# .agents/linked-skills/ is generated and git-ignored: the upstream repos are
+# themselves symlinks, so the links only make sense inside a linked checkout.
 
 set -u
 
-SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
-ROOT=$(cd "$SCRIPT_DIR/../.." && pwd)
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd -P)
+ROOT=$(cd "$SCRIPT_DIR/../.." && pwd -P)
 SRC="$ROOT/.agents/skills"
 DST="$ROOT/.claude/skills"
+LNK="$ROOT/.agents/linked-skills"
+MAX_DEPTH=4
+
+NL='
+'
+TAB=$(printf '\t')
 
 linked=0
+dep_linked=0
 pruned=0
 skipped=0
 
 mkdir -p "$DST" 2>/dev/null || true
 [ -f "$DST/.gitkeep" ] || : > "$DST/.gitkeep" 2>/dev/null || true
 
-# ---- link pass -------------------------------------------------------------
+# ---- local link pass -------------------------------------------------------
 if [ -d "$SRC" ]; then
     for skill_dir in "$SRC"/*/; do
         [ -d "$skill_dir" ] || continue
@@ -59,6 +98,255 @@ if [ -d "$SRC" ]; then
     done
 fi
 
+# ---- dependency resolution -------------------------------------------------
+# An OwlMeans monorepo declares a linked upstream by listing that upstream's
+# packages explicitly as "libraries/<dep>/packages/<pkg>" workspace entries.
+# The dep name is therefore the second path segment of any such entry.
+deps_of() {
+    pkg="$1/package.json"
+    [ -f "$pkg" ] || return 0
+    grep -o '"libraries/[A-Za-z0-9._-][A-Za-z0-9._-]*/packages' "$pkg" 2>/dev/null \
+        | sed 's|^"libraries/||; s|/packages$||' \
+        | awk '!seen[$0]++'
+}
+
+# Resolve libraries/<dep> to the real directory it points at, so every link we
+# create later targets a real path rather than a chain of symlinks.
+resolve_repo() {
+    p="$1/libraries/$2"
+    [ -d "$p" ] || return 0
+    (cd "$p" 2>/dev/null && pwd -P)
+}
+
+# Breadth-first walk: the frontier holds one depth level, so the first repo to
+# claim a skill name is always the nearest dependency.
+visited="$NL$ROOT$NL"
+order=""
+frontier=""
+while IFS= read -r dep; do
+    [ -n "$dep" ] || continue
+    rp=$(resolve_repo "$ROOT" "$dep")
+    [ -n "$rp" ] && frontier="$frontier$rp$NL"
+done <<EOF
+$(deps_of "$ROOT")
+EOF
+
+depth=1
+while [ "$depth" -le "$MAX_DEPTH" ] && [ -n "$frontier" ]; do
+    next=""
+    while IFS= read -r rp; do
+        [ -n "$rp" ] || continue
+        case "$visited" in
+            *"$NL$rp$NL"*) continue ;;
+        esac
+        visited="$visited$rp$NL"
+        order="$order$rp$NL"
+        while IFS= read -r dep; do
+            [ -n "$dep" ] || continue
+            crp=$(resolve_repo "$rp" "$dep")
+            [ -n "$crp" ] && next="$next$crp$NL"
+        done <<EOF
+$(deps_of "$rp")
+EOF
+    done <<EOF
+$frontier
+EOF
+    frontier="$next"
+    depth=$((depth + 1))
+done
+
+# ---- candidate collection --------------------------------------------------
+TMPD=$(mktemp -d 2>/dev/null) || TMPD="${TMPDIR:-/tmp}/link-skills.$$"
+mkdir -p "$TMPD" 2>/dev/null || true
+CAND="$TMPD/candidates"
+: > "$CAND" 2>/dev/null || CAND=""
+
+seen_names="$NL"
+chain=""
+
+record_candidate() {
+    cname="$1"
+    corigin="$2"
+    cpath="$3"
+    [ -f "$cpath/SKILL.md" ] || return 0
+    # A local skill always shadows an upstream one of the same name.
+    [ -f "$SRC/$cname/SKILL.md" ] && return 0
+    case "$seen_names" in
+        *"$NL$cname$NL"*) return 0 ;;
+    esac
+    seen_names="$seen_names$cname$NL"
+    printf '%s\t%s\t%s\n' "$cname" "$corigin" "$cpath" >> "$CAND"
+}
+
+if [ -n "$CAND" ] && [ -n "$order" ]; then
+    while IFS= read -r rp; do
+        [ -n "$rp" ] || continue
+        origin=$(basename "$rp")
+        chain="$chain$origin -> "
+        for skill_dir in "$rp"/.agents/skills/*/; do
+            [ -d "$skill_dir" ] || continue
+            skill_dir="${skill_dir%/}"
+            record_candidate "$(basename "$skill_dir")" "$origin" "$skill_dir"
+        done
+    done <<EOF
+$order
+EOF
+    chain="${chain% -> }"
+elif [ -n "$CAND" ]; then
+    # Standalone consumer: no libraries/* upstreams, so the skills ship inside
+    # the installed packages as generated agent-meta/ copies.  Those packages
+    # are not necessarily at the project root: a workspace whose @owlmeans deps
+    # belong to its sources/* packages keeps them in each package's own
+    # node_modules unless the linker hoists.  So collect the @owlmeans scope
+    # directory of the root and of every directory up to two levels below it.
+    # A directory is scanned only when it is part of THIS project: node_modules
+    # trees are never descended into, and a directory whose real path leaves the
+    # root — a projects/<repo> or libraries/<repo> symlink into a neighbouring
+    # checkout — belongs to that other repository, not to this one.
+    in_tree() {
+        rp=$(cd "$1" 2>/dev/null && pwd -P) || return 1
+        case "$rp/" in
+            "$ROOT"/*) return 0 ;;
+        esac
+        return 1
+    }
+
+    scope_dirs="$ROOT/node_modules/@owlmeans$NL"
+    for lvl1 in "$ROOT"/*/; do
+        [ -d "$lvl1" ] || continue
+        lvl1="${lvl1%/}"
+        [ "$(basename "$lvl1")" = "node_modules" ] && continue
+        in_tree "$lvl1" || continue
+        scope_dirs="$scope_dirs$lvl1/node_modules/@owlmeans$NL"
+        for lvl2 in "$lvl1"/*/; do
+            [ -d "$lvl2" ] || continue
+            lvl2="${lvl2%/}"
+            [ "$(basename "$lvl2")" = "node_modules" ] && continue
+            in_tree "$lvl2" || continue
+            scope_dirs="$scope_dirs$lvl2/node_modules/@owlmeans$NL"
+        done
+    done
+
+    # The same physical package is reachable through several workspaces once the
+    # linker hoists or symlinks it, so key the dedup on the resolved path.
+    seen_pkgs="$NL"
+    while IFS= read -r scope_dir; do
+        [ -n "$scope_dir" ] || continue
+        [ -d "$scope_dir" ] || continue
+        for pkg_dir in "$scope_dir"/*/; do
+            [ -d "$pkg_dir" ] || continue
+            pkg_dir="${pkg_dir%/}"
+            real=$(cd "$pkg_dir" 2>/dev/null && pwd -P) || continue
+            [ -n "$real" ] || continue
+            case "$seen_pkgs" in
+                *"$NL$real$NL"*) continue ;;
+            esac
+            seen_pkgs="$seen_pkgs$real$NL"
+            origin="@owlmeans/$(basename "$pkg_dir")"
+            for skill_dir in "$real"/agent-meta/skills/*/; do
+                [ -d "$skill_dir" ] || continue
+                skill_dir="${skill_dir%/}"
+                record_candidate "$(basename "$skill_dir")" "$origin" "$skill_dir"
+            done
+        done
+    done <<EOF
+$scope_dirs
+EOF
+    [ -s "$CAND" ] && chain="node_modules/@owlmeans/*/agent-meta/skills"
+fi
+
+cand_has() {
+    [ -n "$CAND" ] && [ -f "$CAND" ] || return 1
+    awk -F"$TAB" -v n="$1" '$1 == n { found = 1 } END { exit found ? 0 : 1 }' "$CAND"
+}
+
+# Both directories are resolved absolute paths. Store their relative relationship,
+# so a prepare hook inside /var/sources does not break the host's skill links.
+relative_target() {
+    awk -v base="$1" -v dest="$2" 'BEGIN {
+        nb = split(base, b, "/")
+        nd = split(dest, d, "/")
+        i = 1
+        while (i <= nb && i <= nd && b[i] == d[i]) i++
+        result = ""
+        for (j = i; j <= nb; j++) result = result "../"
+        for (j = i; j <= nd; j++) result = result d[j] (j < nd ? "/" : "")
+        print result == "" ? "." : result
+    }'
+}
+
+# ---- dependency link pass --------------------------------------------------
+if [ -n "$CAND" ] && [ -s "$CAND" ]; then
+    mkdir -p "$LNK" 2>/dev/null || true
+    while IFS="$TAB" read -r name origin path; do
+        [ -n "$name" ] || continue
+        ok=1
+        for target in "$LNK/$name" "$DST/$name"; do
+            if [ -e "$target" ] && [ ! -L "$target" ]; then
+                echo "link-skills: skip '$name' — a real file/directory shadows it in $(dirname "$target")" >&2
+                ok=0
+                continue
+            fi
+            ln -sfn "$(relative_target "$(dirname "$target")" "$path")" "$target" 2>/dev/null || {
+                echo "link-skills: failed to link '$name' from $origin" >&2
+                ok=0
+            }
+        done
+        if [ "$ok" -eq 1 ]; then
+            dep_linked=$((dep_linked + 1))
+        else
+            skipped=$((skipped + 1))
+        fi
+    done < "$CAND"
+fi
+
+# ---- index -----------------------------------------------------------------
+# Read the description straight out of the SKILL.md frontmatter; fall back to
+# the first heading.  Pipes would break the table, so they are folded away.
+describe() {
+    f="$1/SKILL.md"
+    [ -f "$f" ] || return 0
+    d=$(sed -n '/^---[[:space:]]*$/,/^---[[:space:]]*$/p' "$f" \
+        | sed -n 's/^description:[[:space:]]*//p' | head -1)
+    [ -n "$d" ] || d=$(sed -n 's/^#[[:space:]][[:space:]]*//p' "$f" | head -1)
+    d=$(printf '%s' "$d" | sed "s/^[\"']//; s/[\"']\$//; s/|/\//g")
+    if [ "${#d}" -gt 160 ]; then
+        d=$(printf '%s' "$d" | cut -c1-157)...
+    fi
+    printf '%s' "$d"
+}
+
+if [ -n "$CAND" ] && [ -s "$CAND" ]; then
+    {
+        echo "# Linked Skills"
+        echo ""
+        echo "Generated by \`.agents/scripts/link-skills.sh\` — never edit by hand, and never"
+        echo "commit: the entries are symlinks into checkouts that only exist locally."
+        echo ""
+        echo "These skills belong to the repositories this one depends on. They are readable at"
+        echo "\`.agents/linked-skills/<name>/SKILL.md\` and are loaded by Claude Code through"
+        echo "\`.claude/skills/\` like any local skill. A local skill of the same name always wins,"
+        echo "and a nearer dependency wins over a farther one."
+        echo ""
+        echo "Dependency order: $chain"
+        echo ""
+        echo "| skill | origin repo | description |"
+        echo "|---|---|---|"
+        LC_ALL=C sort -t"$TAB" -k1,1 "$CAND" | while IFS="$TAB" read -r name origin path; do
+            [ -n "$name" ] || continue
+            printf '| %s | %s | %s |\n' "$name" "$origin" "$(describe "$path")"
+        done
+    } > "$TMPD/INDEX.md" 2>/dev/null
+
+    if [ -f "$TMPD/INDEX.md" ]; then
+        if cmp -s "$TMPD/INDEX.md" "$LNK/INDEX.md" 2>/dev/null; then
+            :
+        else
+            cp "$TMPD/INDEX.md" "$LNK/INDEX.md" 2>/dev/null || true
+        fi
+    fi
+fi
+
 # ---- prune pass ------------------------------------------------------------
 if [ -d "$DST" ]; then
     for entry in "$DST"/* "$DST"/.[!.]*; do
@@ -67,16 +355,40 @@ if [ -d "$DST" ]; then
         [ "$name" = ".gitkeep" ] && continue
         [ -L "$entry" ] || continue
 
-        if [ ! -e "$entry" ] || [ ! -f "$SRC/$name/SKILL.md" ]; then
-            rm -f "$entry" 2>/dev/null && pruned=$((pruned + 1))
+        if [ -f "$SRC/$name/SKILL.md" ]; then
+            continue
+        fi
+        if cand_has "$name" && [ -f "$entry/SKILL.md" ]; then
+            continue
         fi
+        rm -f "$entry" 2>/dev/null && pruned=$((pruned + 1))
     done
 fi
 
-if [ "$skipped" -gt 0 ]; then
-    echo "link-skills: $linked linked, $pruned pruned, $skipped skipped"
-else
-    echo "link-skills: $linked linked, $pruned pruned"
+if [ -d "$LNK" ]; then
+    for entry in "$LNK"/*; do
+        [ -e "$entry" ] || [ -L "$entry" ] || continue
+        name=$(basename "$entry")
+        [ "$name" = "INDEX.md" ] && continue
+        [ -L "$entry" ] || continue
+
+        if cand_has "$name" && [ -f "$entry/SKILL.md" ]; then
+            continue
+        fi
+        rm -f "$entry" 2>/dev/null && pruned=$((pruned + 1))
+    done
+    # Nothing linked at all — leave no empty generated directory behind.
+    if [ -z "${CAND:-}" ] || [ ! -s "$CAND" ]; then
+        rm -f "$LNK/INDEX.md" 2>/dev/null || true
+        rmdir "$LNK" 2>/dev/null || true
+    fi
 fi
 
+rm -rf "$TMPD" 2>/dev/null || true
+
+summary="link-skills: $linked linked, $pruned pruned"
+[ "$dep_linked" -gt 0 ] && summary="$summary, $dep_linked from dependencies"
+[ "$skipped" -gt 0 ] && summary="$summary, $skipped skipped"
+echo "$summary"
+
 exit 0

package/template/_agents/skills/agent-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-memory
-description: Shared agent memory protocol — the .agents/memory/ graph store every agent reads and writes: MEMORY.md index, subsystem nodes, compact-on-write merging, size caps, and the read protocol. Use when reading or writing project memory, when asked to remember something, or to decide where knowledge belongs.
+description: "Shared agent memory protocol — the .agents/memory/ graph store every agent reads and writes: MEMORY.md index, subsystem nodes, compact-on-write merging, size caps, and the read protocol. Use when reading or writing project memory, when asked to remember something, or to decide where knowledge belongs."
 user-invocable: true
 metadata:
   scope: general
@@ -14,8 +14,8 @@ 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/`, `~/.claude/`, `~/.copilot/`, or
-anywhere outside the repository. Legacy `.claude/memory/` / `.github/memory/` stores are
-retired — if one exists, flag it for `memory-recompact` migration instead of writing there.
+anywhere outside the repository. Records found in any such place are folded into
+`.agents/memory/` by `memory-recompact`, never added to.
 
 ## Store layout
 
@@ -105,8 +105,8 @@ Every write is a merge, never an append:
 4. **Compact** — reread the node; collapse redundancy; delete anything the code or git history
    now states; prune resolved `Status` lines.
 5. **Cap** — over soft cap: compact harder. Over hard cap: split by sub-scope into a linked child
-   node, or promote procedure-shaped overflow (`memory-promotion` where present, else
-   `skill-authoring`).
+   node, or promote procedure-shaped overflow (`memory-promotion` where present, else the
+   project's `skill-authoring` or `create-skill` skill).
 6. **Index** — update the hook line if the node's center of gravity moved; bump `updated:`.
 
 ## Knowledge, not events
@@ -116,10 +116,10 @@ correctly, stated without reference to this session?* Keep invariants, cause→e
 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."
+Before (event log): "2026-06-11 — CI red on the second run; the migration step was not idempotent,
+patched it, re-ran green."
+After (knowledge): "The migration step is idempotent — run against an already-migrated database
+it writes nothing; a second run that still reports work means the first did not converge."
 
 ## Size caps (hard)
 
@@ -135,8 +135,9 @@ each repo — fan every fix out to all copies; verify with `diff`. Correct re-ru
 ## Memory vs skill
 
 Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") becomes a skill —
-follow `memory-promotion` where present, otherwise `skill-authoring`. Repeated use of a node to
-*perform* tasks, and over-cap nodes full of steps, are promotion triggers.
+follow `memory-promotion` where present, otherwise the project's `skill-authoring` or
+`create-skill` skill. Repeated use of a node to *perform* tasks, and over-cap nodes full of
+steps, are promotion triggers.
 
 Promotion is a **rewrite, never a move**: never paste node text into a skill. "Record the rule,
 not the story" and the size caps above bind skill bodies at least as tightly as they bind nodes