@agfpd/iapeer 0.2.7 → 0.2.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.7",
-  "description": "Foundation core for the IAPeer multi-agent ecosystem: identity, registry, storage, codec.",
+  "version": "0.2.9",
+  "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {
     "iapeer": "bin/iapeer"

package/src/cli/cli.test.ts

@@ -128,7 +128,7 @@ describe('send validation', () => {
     await register('alpha')
     await expect(
       sendMessage({ from: 'claude-alpha', target: 'nobody', message: 'hi', env: env() }),
-    ).rejects.toThrow(/not in the IAPeer peers index|self/)
+    ).rejects.toThrow(/not in the iapeer peers index|self/)
   })
 })
 

package/src/core/constants.ts

@@ -1,4 +1,4 @@
-// Canonical constants for the IAPeer foundation.
+// Canonical constants for the iapeer foundation.
 // Consolidated from inter-agent-protocol/src/lib/constants.ts (wins as-is) and
 // extended with storage-layer path names (blueprint §1 core/constants).
 
@@ -131,6 +131,14 @@ export function resolveSockDir(env: NodeJS.ProcessEnv = process.env): string {
 // === per-peer cwd scope ===
 export const IAPEER_DIR = '.iapeer'
 export const PEER_PROFILE_FILE = 'peer-profile.json'
+// Doctrine-fragments layer (Канал A, слой 5): a primitive-owned `.iapeer/fragments/`
+// subdir under BOTH the global root (`~/.iapeer/fragments/`, host-wide) and the
+// per-peer cwd (`<cwd>/.iapeer/fragments/`, per-peer). Holds machine-regenerated
+// `*.md` fragments that an ecosystem primitive writes + rotates itself (e.g.
+// iapeer-memory's guide + per-peer note index) — merged into the system prompt so
+// the context survives compaction, yet kept OUT of the hand-authored IAPEER.md
+// doctrine (two writers, mutual-rollback). See composeSystemPrompt Layer 5.
+export const FRAGMENTS_DIR = 'fragments'
 
 // === global scope ~/.iapeer/ ===
 export const IAP_PLUGIN_DIR = 'iap'

package/src/daemon/daemon.test.ts

@@ -93,7 +93,7 @@ describe('callTool (no wake passed → Ф1 offline behaviour, never spawns)', ()
     const caller = resolveCallerFromHeader('claude-boris', readPeersIndex())
     const r = await callTool(caller, 'send_to_peer', { personality: 'nobody', message: 'hi' })
     expect(r.isError).toBe(true)
-    expect(r.content[0].text).toMatch(/not in the IAPeer peers index/)
+    expect(r.content[0].text).toMatch(/not in the iapeer peers index/)
   })
 
   test('unknown tool → error', async () => {

package/src/daemon/index.ts

@@ -77,7 +77,7 @@ export function resolveCallerFromHeader(value: string | undefined, index: PeersI
 
 export function buildSendDescription(index: PeersIndex): string {
   const lines = [
-    'Send a message to a known IAPeer peer through Inter-Agent-Protocol.',
+    'Send a message to a known iapeer peer through Inter-Agent-Protocol.',
     'Peers can be agents, humans, or services. Runtime is the delivery surface, not the peer type.',
     'Current delivery supports any runtime endpoint that follows the IAP tmux socket convention. Claude/Codex are built-in local runtimes; external runtimes such as telegram can be exposed by runtime-router packages.',
     '',

package/src/launch/adapters/claude.ts

@@ -10,7 +10,7 @@
 //     (the dev-channels "I am using this for local development" Enter, 335-345).
 //   - Spawned-Peer/src/spawner.ts — buildClaudeArgv (759-787: same flags +
 //     optional --resume <uuid>) and findLatestTranscript (522-538: resume uuid).
-//   - IAPeer/src/lifecycle/index.ts — claudeInputReady / claudeBootDialog /
+//   - iapeer/src/lifecycle/index.ts — claudeInputReady / claudeBootDialog /
 //     newestClaudeTranscriptMtime / findLatestClaudeTranscript. This is the
 //     canonical port: the slug is realpath(cwd).replace(/[^a-zA-Z0-9]/g,'-') —
 //     claude encodes EVERY non-alphanumeric char (not just '/'); the old

package/src/launch/composeSystemPrompt.layers.test.ts

@@ -130,6 +130,65 @@ describe('composeSystemPrompt — layer 4 (other domains)', () => {
   })
 })
 
+describe('composeSystemPrompt — layer 5 (doctrine fragments)', () => {
+  const frag = (over: Partial<PromptDomainBlock>): PromptDomainBlock => ({ domain: 'F', ...over })
+
+  test('empty/omitted fragments add NOTHING (legacy bytes preserved)', () => {
+    const legacy = composeSystemPrompt(base)
+    expect(composeSystemPrompt({ ...base, promptFragments: [] })).toBe(legacy)
+    expect(composeSystemPrompt({ ...base, promptFragments: undefined })).toBe(legacy)
+  })
+
+  test('a presence-marker fragment (empty halves) emits no text and no dangling separator', () => {
+    const legacy = composeSystemPrompt(base)
+    expect(composeSystemPrompt({ ...base, promptFragments: [frag({ local: '' })] })).toBe(legacy)
+    expect(composeSystemPrompt({ ...base, promptFragments: [frag({ global: '', local: '' })] })).toBe(legacy)
+    const out = composeSystemPrompt({
+      ...base,
+      promptFragments: [frag({ domain: 'EMPTY', local: '' }), frag({ domain: 'REAL', local: 'idx-content\n' })],
+    })
+    expect(out).toContain('idx-content')
+    expect(out).not.toMatch(/\n{4,}/)
+  })
+
+  test('within a fragment stem, global (host-wide guide) precedes local (per-peer index)', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      promptFragments: [frag({ domain: 'MEM', global: 'mem-guide', local: 'mem-index' })],
+    })
+    expect(out).toContain('mem-guide\nmem-index')
+    expect(out.indexOf('mem-guide')).toBeLessThan(out.indexOf('mem-index'))
+  })
+
+  test('layer 5 sits AFTER layer 4 (most-volatile last), separated by a blank line', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      pluginDomains: [{ domain: 'D', global: 'domain-text' }],
+      promptFragments: [{ domain: 'MEM', local: 'fragment-text' }],
+    })
+    expect(out.indexOf('domain-text')).toBeLessThan(out.indexOf('fragment-text'))
+    expect(out).toContain('domain-text\n\nfragment-text')
+  })
+
+  test('full 5-layer ordering: YAML → doctrine → registry → domains → fragments', () => {
+    const out = composeSystemPrompt({
+      ...base,
+      peers: [peerA],
+      pluginDomains: [{ domain: 'D', global: 'domain-text' }],
+      promptFragments: [{ domain: 'MEM', global: 'fragment-text' }],
+    })
+    const order = [
+      out.indexOf('personality:'),
+      out.indexOf('Be the implementer.'),
+      out.indexOf('## Known peers'),
+      out.indexOf('domain-text'),
+      out.indexOf('fragment-text'),
+    ]
+    expect(order.every(i => i >= 0)).toBe(true)
+    expect(order).toEqual([...order].sort((a, b) => a - b))
+  })
+})
+
 // ─────────────────────────────────────────────────────────────────────────────
 // gatherPromptInput — FS discovery over ~/.iapeer + <cwd>/.iapeer
 // ─────────────────────────────────────────────────────────────────────────────
@@ -161,6 +220,17 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     // a non-.md file must be ignored
     writeFileSync(join(localRoot, 'peer-profile.json'), '{}')
 
+    // Layer 5 — fragments/ subdir of both roots: a paired stem (host-wide guide +
+    // per-peer index) and a global-only fragment; a non-.md file must be ignored.
+    const globalFrags = join(globalRoot, 'fragments')
+    const localFrags = join(localRoot, 'fragments')
+    mkdirSync(globalFrags, { recursive: true })
+    mkdirSync(localFrags, { recursive: true })
+    writeFileSync(join(globalFrags, 'iapeer-memory.md'), 'mem-guide\n') // host-wide guide
+    writeFileSync(join(localFrags, 'iapeer-memory.md'), 'mem-index\n') // per-peer index
+    writeFileSync(join(globalFrags, 'other-primitive.md'), 'other-frag\n')
+    writeFileSync(join(localFrags, 'notes.txt'), 'ignored') // non-.md, must be ignored
+
     // Layer 3 — registry at the global root (deliberately UNSORTED on disk)
     const index = {
       version: 2,
@@ -207,6 +277,23 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(byName.MARKER).toEqual({ domain: 'MARKER', local: '' }) // present but empty
   })
 
+  test('layer 5: fragments/ subdir scanned, paired by stem (guide global + index local), sorted', () => {
+    const input = gather()
+    const frags = input.promptFragments ?? []
+    expect(frags.map(f => f.domain)).toEqual(['iapeer-memory', 'other-primitive'])
+    const byName = Object.fromEntries(frags.map(f => [f.domain, f]))
+    expect(byName['iapeer-memory']).toEqual({ domain: 'iapeer-memory', global: 'mem-guide\n', local: 'mem-index\n' })
+    expect(byName['other-primitive']).toEqual({ domain: 'other-primitive', global: 'other-frag\n' })
+    // the non-.md notes.txt never became a fragment
+    expect(frags.map(f => f.domain)).not.toContain('notes')
+  })
+
+  test('layer 5: fragments are NOT confused with the root-level Layer-4 domains', () => {
+    const input = gather()
+    // the fragments dir itself is a directory, not a `.md` file → never a Layer-4 domain
+    expect((input.pluginDomains ?? []).map(d => d.domain)).not.toContain('fragments')
+  })
+
   test('layer 3: registry projected to EXACTLY 5 fields, sorted by personality', () => {
     const input = gather()
     expect((input.peers ?? []).map(p => p.personality)).toEqual(['arthur', 'boris'])
@@ -237,14 +324,19 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(prompt).toContain('aaa-global-only')
     expect(prompt).toContain('mm-global\nmm-local')
     expect(prompt).toContain('zzz-local-only')
+    // Layer 5 (fragments: guide+index paired, global-only fragment)
+    expect(prompt).toContain('mem-guide\nmem-index')
+    expect(prompt).toContain('other-frag')
 
     const order = [
       prompt.indexOf('personality: "iapeer"'),
       prompt.indexOf('LOCAL ROLE'),
       prompt.indexOf('## Known peers'),
       prompt.indexOf('aaa-global-only'),
+      prompt.indexOf('mem-guide'), // Layer 5 — after every Layer-4 domain
     ]
     expect(order).toEqual([...order].sort((a, b) => a - b))
+    expect(prompt.indexOf('zzz-local-only')).toBeLessThan(prompt.indexOf('mem-guide'))
     // marker file produced no content and no blank-block artifact
     expect(prompt).not.toContain('MARKER')
     expect(prompt).not.toMatch(/\n{4,}/)
@@ -263,6 +355,7 @@ describe('gatherPromptInput — FS discovery of all 4 layers', () => {
     expect(input.peerDoctrine).toBe('')
     expect(input.globalDoctrine).toBeUndefined()
     expect(input.pluginDomains).toEqual([])
+    expect(input.promptFragments).toEqual([]) // no fragments/ subdir → empty layer
     expect(input.peers).toEqual([])
     // composes to just the YAML block (+ empty doctrine), no extra layers
     const prompt = composeSystemPrompt(input)

package/src/launch/composeSystemPrompt.ts

@@ -10,7 +10,7 @@
 
 import { readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
-import { IAPEER_DIR } from '../core/constants.ts'
+import { FRAGMENTS_DIR, IAPEER_DIR } from '../core/constants.ts'
 import { publicPeerSummary, readPeersIndex, type PublicPeerSummary } from '../registry/index.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import type { ComposePromptInput, PromptDomainBlock } from './types.ts'
@@ -93,11 +93,14 @@ export function composeSystemPrompt(input: ComposePromptInput): string {
   // jq output — the golden test pins this exactly.
   const layer12 = yaml + global + input.peerDoctrine
 
-  // Layer 3 (registry) and Layer 4 (other domains) are appended ONLY when they
-  // have content.
+  // Layer 3 (registry), Layer 4 (operator/plugin domains) and Layer 5 (primitive
+  // doctrine fragments) are appended ONLY when they have content. Layer 5 sits LAST
+  // — it is the most volatile (machine-regenerated on every source change), so it
+  // never disturbs the stable prefix (YAML + doctrine + registry + domains) above it.
   const layer3 = renderRegistry(input.peers ?? [])
-  const layer4 = renderDomains(input.pluginDomains ?? [])
-  const sections = [layer12, layer3, layer4].filter(section => section.length > 0)
+  const layer4 = renderMergedBlocks(input.pluginDomains ?? [])
+  const layer5 = renderMergedBlocks(input.promptFragments ?? [])
+  const sections = [layer12, layer3, layer4, layer5].filter(section => section.length > 0)
 
   // ONE section (no registry, no extra domains) → the legacy bytes, UNTOUCHED —
   // the golden test pins layer12 exactly (peerDoctrine verbatim, incl. its own
@@ -129,36 +132,42 @@ function renderRegistry(peers: readonly PublicPeerSummary[]): string {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Layer 4 — every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root, merged
-// general → specific (global then local). The merge is ORGANIC: domain stems are
-// used only for stable ordering (done by the gatherer), never emitted — custom
-// operator files (SPAWNER_INSTRUCTIONS.md, …) flow in as ordinary domains. An
-// empty file is a presence marker (Канал B) and contributes no text here.
+// Layers 4 & 5 — merged global/local blocks. Shared renderer:
+//   • Layer 4: every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root (operator /
+//     plugin user-settings; SPAWNER_INSTRUCTIONS.md, … flow in organically).
+//   • Layer 5: every `<STEM>.md` pair in .iapeer/fragments/ (primitive-owned,
+//     machine-regenerated doctrine fragments — iapeer-memory's guide + note index).
+// Both merge general → specific (global then local). The merge is ORGANIC: stems
+// are used only for stable ordering (done by the gatherer), never emitted. An empty
+// file is a presence marker (Канал B) and contributes no text — so a fragment dir
+// that drops to a 0-byte placeholder, or whose file vanishes mid-rotation, yields
+// nothing here rather than a dangling separator.
 // ─────────────────────────────────────────────────────────────────────────────
 
-function renderDomains(domains: readonly PromptDomainBlock[]): string {
-  const blocks: string[] = []
-  for (const d of domains) {
-    // Per domain: global then local (general → specific), each trimmed of its
+function renderMergedBlocks(blocks: readonly PromptDomainBlock[]): string {
+  const out: string[] = []
+  for (const b of blocks) {
+    // Per stem: global then local (general → specific), each trimmed of its
     // trailing newlines so a 0-byte marker (or a newline-only file) drops out and
-    // the spacing is uniform. Halves of one domain are kept tight (single '\n');
-    // distinct domains are separated by a blank line below.
-    const halves = [d.global, d.local]
+    // the spacing is uniform. Halves of one stem are kept tight (single '\n');
+    // distinct stems are separated by a blank line below.
+    const halves = [b.global, b.local]
       .filter((s): s is string => s !== undefined)
       .map(s => s.replace(/\n+$/, ''))
       .filter(s => s.length > 0)
-    if (halves.length > 0) blocks.push(halves.join('\n'))
+    if (halves.length > 0) out.push(halves.join('\n'))
   }
-  return blocks.join('\n\n')
+  return out.join('\n\n')
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // gatherPromptInput — the FS-discovery half: scan ~/.iapeer/*.md (global) and
 // <cwd>/.iapeer/*.md (local), split IAPEER.md (Layer 2) from every other domain
-// (Layer 4), and project the live registry through publicPeerSummary (Layer 3),
-// into a ready-to-render ComposePromptInput. Layer-1 identity/host facts are
-// supplied by the caller (lifecycle gathers them via sw_vers/hostname/etc).
-// This is the ONLY FS-touching part; composeSystemPrompt itself stays pure.
+// (Layer 4), scan the fragments/ subdir of both roots (Layer 5), and project the
+// live registry through publicPeerSummary (Layer 3), into a ready-to-render
+// ComposePromptInput. Layer-1 identity/host facts are supplied by the caller
+// (lifecycle gathers them via sw_vers/hostname/etc). This is the ONLY FS-touching
+// part; composeSystemPrompt itself stays pure.
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface GatherPromptOptions {
@@ -187,28 +196,51 @@ function readFileIfPresent(path: string): string | undefined {
   }
 }
 
-/** `*.md` files directly at a `.iapeer` root (NOT recursing), excluding IAPEER.md
- *  (Layer 2) — the domain candidates for Layer 4. Missing dir → [].
- *  The `.md` test and the doctrine exclusion are CASE-INSENSITIVE: the Layer-2
- *  read (join(root,'IAPEER.md')) resolves a lowercase `iapeer.md` on a case-
- *  insensitive FS (macOS APFS), so a byte-exact exclusion here would let that same
- *  file ALSO surface as a Layer-4 domain and duplicate the doctrine. Lowercasing
- *  both also picks up an uppercase-extension `NOTES.MD` (spec: no root MD ignored). */
-function listDomainFiles(root: string): string[] {
-  const doctrineLower = IAPEER_DOCTRINE_FILE.toLowerCase()
+/** `*.md` files directly in `dir` (NOT recursing). Missing dir → []. The `.md`
+ *  test is CASE-INSENSITIVE so an uppercase-extension `NOTES.MD` is picked up too. */
+function listMdFiles(dir: string): string[] {
   try {
-    return readdirSync(root, { withFileTypes: true })
-      .filter(e => {
-        if (!e.isFile()) return false
-        const lower = e.name.toLowerCase()
-        return lower.endsWith('.md') && lower !== doctrineLower
-      })
+    return readdirSync(dir, { withFileTypes: true })
+      .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.md'))
       .map(e => e.name)
   } catch {
     return []
   }
 }
 
+/** Layer-4 domain candidates: `*.md` directly at a `.iapeer` root, excluding
+ *  IAPEER.md (Layer 2). The doctrine exclusion is CASE-INSENSITIVE: the Layer-2
+ *  read (join(root,'IAPEER.md')) resolves a lowercase `iapeer.md` on a case-
+ *  insensitive FS (macOS APFS), so a byte-exact exclusion here would let that same
+ *  file ALSO surface as a Layer-4 domain and duplicate the doctrine. */
+function listDomainFiles(root: string): string[] {
+  const doctrineLower = IAPEER_DOCTRINE_FILE.toLowerCase()
+  return listMdFiles(root).filter(name => name.toLowerCase() !== doctrineLower)
+}
+
+/** Build a list of merged global/local blocks (Layer 4 OR Layer 5) from the
+ *  union of `*.md` stems present in the global and/or local dir, sorted by
+ *  filename (plain codepoint order) for a deterministic prompt. `lister` selects
+ *  the candidate `.md` files — Layer 4 excludes the IAPEER.md doctrine, Layer 5
+ *  takes every fragment. A read that races a rotation (file removed between listdir
+ *  and read) → that half is undefined and drops out; a 0-byte file → '' and is
+ *  dropped by the renderer. */
+function gatherMergedBlocks(
+  globalDir: string,
+  localDir: string,
+  lister: (dir: string) => string[] = listMdFiles,
+): PromptDomainBlock[] {
+  const names = new Set<string>([...lister(globalDir), ...lister(localDir)])
+  return [...names].sort().map(name => {
+    const block: PromptDomainBlock = { domain: name.slice(0, -3) } // strip ".md"
+    const global = readFileIfPresent(join(globalDir, name))
+    const local = readFileIfPresent(join(localDir, name))
+    if (global !== undefined) block.global = global
+    if (local !== undefined) block.local = local
+    return block
+  })
+}
+
 export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput {
   const env = opts.env ?? process.env
   const globalRoot = opts.globalRoot ?? resolveGlobalRoot(env)
@@ -220,20 +252,19 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
   const peerDoctrine = readFileIfPresent(join(localRoot, IAPEER_DOCTRINE_FILE)) ?? ''
 
   // Layer 4 — union of every non-IAPEER domain present globally and/or locally,
-  // sorted by filename for a deterministic prompt (plain codepoint order). Empty
-  // (0-byte) files stay as presence markers — readFileIfPresent returns '', and
-  // renderDomains drops empty halves, so a marker contributes no text/separator.
-  const domainNames = new Set<string>([...listDomainFiles(globalRoot), ...listDomainFiles(localRoot)])
-  const pluginDomains: PromptDomainBlock[] = [...domainNames]
-    .sort()
-    .map(name => {
-      const block: PromptDomainBlock = { domain: name.slice(0, -3) } // strip ".md"
-      const global = readFileIfPresent(join(globalRoot, name))
-      const local = readFileIfPresent(join(localRoot, name))
-      if (global !== undefined) block.global = global
-      if (local !== undefined) block.local = local
-      return block
-    })
+  // sorted by filename for a deterministic prompt. Empty (0-byte) files stay as
+  // presence markers — readFileIfPresent returns '', and the renderer drops empty
+  // halves, so a marker contributes no text/separator.
+  const pluginDomains = gatherMergedBlocks(globalRoot, localRoot, listDomainFiles)
+
+  // Layer 5 — doctrine fragments: every `*.md` in the fragments/ subdir of both
+  // roots, merged per stem (global guide → per-peer specifics). Primitive-owned and
+  // machine-regenerated; an atomic rotation that briefly removes/replaces a file is
+  // tolerated (a racing read just drops that half — no partial bytes, no throw).
+  const promptFragments = gatherMergedBlocks(
+    join(globalRoot, FRAGMENTS_DIR),
+    join(localRoot, FRAGMENTS_DIR),
+  )
 
   // Layer 3 — peers projected through the shared normalizer, sorted by personality
   // (determinism even if the on-disk file was hand-edited). `opts.peers` lets a
@@ -257,5 +288,6 @@ export function gatherPromptInput(opts: GatherPromptOptions): ComposePromptInput
     ...(globalDoctrine !== undefined ? { globalDoctrine } : {}),
     peers,
     pluginDomains,
+    promptFragments,
   }
 }

package/src/launch/types.ts

@@ -20,7 +20,7 @@ export type { PublicPeerSummary } from '../registry/index.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // composeSystemPrompt — the layered Канал-A merge (docs/Сборка системного
-// промпта — слои и каналы.md). Four layers, general → specific (local overrides
+// промпта — слои и каналы.md). Five layers, general → specific (local overrides
 // global):
 //   1. System YAML (identity + host facts) — jq-GOLDEN, byte-for-byte.
 //   2. iapeer doctrine: ~/.iapeer/IAPEER.md (global) + <cwd>/.iapeer/IAPEER.md (local).
@@ -28,19 +28,27 @@ export type { PublicPeerSummary } from '../registry/index.ts'
 //   4. Plugin user-settings: every OTHER <DOMAIN>.md at the .iapeer/ root, global
 //      + local merged per domain. Custom files (SPAWNER_INSTRUCTIONS.md, …) flow
 //      in organically here — no special-casing.
+//   5. Doctrine fragments: every `*.md` in the `.iapeer/fragments/` subdir, global
+//      (~/.iapeer/fragments/) + local (<cwd>/.iapeer/fragments/) merged per stem.
+//      PRIMITIVE-owned, machine-regenerated (iapeer-memory's guide + note index, …)
+//      — a dedicated namespace kept OUT of the hand-authored IAPEER.md doctrine so
+//      the auto-writer and the human writer never share a file. Sits LAST: the most
+//      volatile layer, so edits to it never disturb the stable prefix above.
 // composeSystemPrompt is a PURE renderer over already-gathered data; the FS
 // discovery lives in gatherPromptInput (mirrors the bash split: shell read the
 // files, the renderer just laid out bytes).
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** One Layer-4 domain: the global + local halves of a single `<DOMAIN>.md` pair
- *  (either may be absent). `domain` is the filename stem, used only for stable
- *  ordering — it is NOT emitted (the merge is organic, per the contract). */
+/** One merged block: the global + local halves of a single stem (either may be
+ *  absent), used for BOTH Layer 4 (`<DOMAIN>.md` at the .iapeer/ root) and Layer 5
+ *  (`<STEM>.md` in .iapeer/fragments/). `domain` is the filename stem, used only
+ *  for stable ordering — it is NOT emitted (the merge is organic). Within a block
+ *  global precedes local (general → specific). */
 export interface PromptDomainBlock {
   domain: string
-  /** ~/.iapeer/<DOMAIN>.md content (general). */
+  /** Global half content (general): ~/.iapeer/<DOMAIN>.md or ~/.iapeer/fragments/<STEM>.md. */
   global?: string
-  /** <cwd>/.iapeer/<DOMAIN>.md content (specific — overrides global). */
+  /** Local half content (specific — overrides global): <cwd>/.iapeer/… counterpart. */
   local?: string
 }
 
@@ -66,6 +74,10 @@ export interface ComposePromptInput {
   /** Layer 4: every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root. Empty/
    *  omitted → the layer emits nothing. */
   pluginDomains?: PromptDomainBlock[]
+  /** Layer 5: every `<STEM>.md` pair in the .iapeer/fragments/ subdir (global +
+   *  local), primitive-owned and machine-regenerated. Empty/omitted → the layer
+   *  emits nothing. Appended LAST (after Layer 4). */
+  promptFragments?: PromptDomainBlock[]
 }
 
 /**
@@ -87,10 +99,12 @@ export interface ComposePromptInput {
  *   peerDoctrine
  *   [\n\n + registry section  — only when peers.length > 0]
  *   [\n\n + merged domains    — only when pluginDomains is non-empty]
+ *   [\n\n + merged fragments  — only when promptFragments is non-empty]
  *
- * Layers 1+2 are byte-for-byte the legacy jq output; layers 3+4 are appended
+ * Layers 1+2 are byte-for-byte the legacy jq output; layers 3+4+5 are appended
  * (each as a `\n\n`-separated section) ONLY when they have content, so a peer
- * with no registry and no extra domains produces the exact legacy bytes.
+ * with no registry, no extra domains and no fragments produces the exact legacy
+ * bytes.
  *
  * Each YAML value is a JSON string literal (jq @json: JSON.stringify), which is
  * also a valid YAML double-quoted scalar — safe against colons/quotes/newlines.

package/src/transport/index.ts

@@ -469,7 +469,7 @@ export async function routeSend(
   const index = readPeersIndex()
   const peer = findPeer(index, personality)
   if (!peer) {
-    return err(`peer "${personality}" is not in the IAPeer peers index; message NOT delivered`)
+    return err(`peer "${personality}" is not in the iapeer peers index; message NOT delivered`)
   }
 
   // Built once — it is both the live-delivery payload and, on a miss, the wake

package/src/update/index.ts

@@ -6,9 +6,10 @@
 // Flow:
 //   1. latest = `npm view @agfpd/iapeer version`           (the cloud's truth)
 //   2. installed == latest && !--force → "already latest"  (no needless rebuild/restart)
-//   3. `npx @agfpd/iapeer@<latest> install`                (fetch + rebuild ~/.local/bin/iapeer
-//      atomically; the COMPILED binary can't rebuild itself from source, so we shell to
-//      npx, which runs the freshly-fetched package's own install — same path consumers use)
+//   3. fetch the published tarball + build from its SOURCE (defaultRunInstall) — the
+//      COMPILED binary can't rebuild itself, so we pull the freshly-published package
+//      and run ITS own source installer. DELIBERATELY NOT `npx … install` (see
+//      defaultRunInstall for why npx is unsafe here).
 //   4. kickstart com.agfpd.iapeer IF loaded                (activate the new binary)
 //
 // Scope: the foundation ONLY (the @agfpd/iapeer binary + its daemon). It never
@@ -20,7 +21,10 @@
 // unit-testable with no network and no launchctl; the defaults are the real impls.
 
 import { spawnSync } from 'child_process'
+import { mkdtempSync, readdirSync, rmSync } from 'fs'
 import { connect } from 'net'
+import { tmpdir } from 'os'
+import { join } from 'path'
 import { IapError } from '../core/errors.ts'
 import { IAPEER_VERSION } from '../core/version.ts'
 import { kickstartDaemon, type DaemonRestartResult } from '../launch/launchd.ts'
@@ -144,14 +148,51 @@ function defaultResolveVersion(spec: string, env: NodeJS.ProcessEnv): string | n
   return SEMVER_RE.test(v) ? v : null
 }
 
-/** Default installer: `npx -y @agfpd/iapeer@<version> install` (pull from cloud + rebuild). */
+/**
+ * Default installer — fetch the published tarball and build from its SOURCE,
+ * DELIBERATELY bypassing `npx`. Pull from the cloud + rebuild ~/.local/bin/iapeer.
+ *
+ * Why not `npx -y @agfpd/iapeer@<v> install`: the package's bin is named `iapeer`,
+ * and once `~/.local/bin/iapeer` is on PATH (true on every host AFTER the first
+ * install) npx resolves that bin NAME to the COMPILED binary already on PATH and
+ * runs ITS `install` — which cannot rebuild itself from source (`bun build --compile`
+ * gets a `/$bunfs/root` entrypoint → FileNotFound) — instead of fetching + running the
+ * freshly-published source. Verified reproducible (09.06, 0.2.8 deploy): with NO
+ * `iapeer` on PATH the same npx invocation prints `command not found` — it never
+ * installs the package — so this is a structural bin-name collision, NOT the
+ * publish-propagation transient (waiting/retry does not cure it).
+ *
+ * Deterministic path instead — no npx command-resolution in the loop:
+ *   1. `npm pack <pkg>@<v>` → the published tarball (rooted at `package/`).
+ *   2. `tar xzf` → extract.
+ *   3. `npm install --omit=dev` in the extracted dir — the tarball ships only
+ *      src/bin (no node_modules), and the source build imports prod deps
+ *      (@modelcontextprotocol/sdk, …).
+ *   4. run the package's OWN bin shim `bash <pkg>/bin/iapeer install` — that is
+ *      `bun src/cli/index.ts install` from the REAL fetched source → builds the prod
+ *      binary atomically (keeps `.prev`).
+ * Needs npm + tar + bash + bun on PATH (the toolchain the bootstrap already assumes).
+ */
 function defaultRunInstall(version: string, env: NodeJS.ProcessEnv): boolean {
   if (env.IAPEER_TEST_SANDBOX === '1') {
-    // A real npx install rebuilds the prod ~/.local/bin/iapeer — never under a test.
-    throw new IapError('refusing a real `npx install` under IAPEER_TEST_SANDBOX=1 — inject runInstall in tests')
+    // A real install rebuilds the prod ~/.local/bin/iapeer — never under a test.
+    throw new IapError('refusing a real install under IAPEER_TEST_SANDBOX=1 — inject runInstall in tests')
+  }
+  const tmp = mkdtempSync(join(tmpdir(), 'iapeer-deploy-'))
+  try {
+    const pack = spawnSync('npm', ['pack', '--silent', '--pack-destination', tmp, `${IAPEER_PACKAGE}@${version}`], { encoding: 'utf8', env })
+    if (pack.status !== 0) return false
+    const tgz = readdirSync(tmp).find(f => f.endsWith('.tgz'))
+    if (!tgz) return false
+    if (spawnSync('tar', ['xzf', join(tmp, tgz), '-C', tmp], { env }).status !== 0) return false
+    const pkg = join(tmp, 'package') // npm-pack tarballs always root at `package/`
+    const deps = spawnSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund', '--silent'], { cwd: pkg, stdio: 'inherit', env })
+    if (deps.status !== 0) return false
+    const build = spawnSync('bash', [join(pkg, 'bin', 'iapeer'), 'install'], { stdio: 'inherit', env })
+    return build.status === 0
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
   }
-  const r = spawnSync('npx', ['-y', `${IAPEER_PACKAGE}@${version}`, 'install'], { stdio: 'inherit', env })
-  return r.status === 0
 }
 
 /**

package/src/update/update.test.ts

@@ -137,9 +137,9 @@ describe('updateIapeer — failure paths', () => {
 })
 
 describe('updateIapeer — real-installer sandbox guard', () => {
-  test('default runInstall refuses a real npx install under IAPEER_TEST_SANDBOX', () => {
+  test('default runInstall refuses a real install under IAPEER_TEST_SANDBOX', () => {
     // fetchLatest injected (newer) so the gate proceeds to the DEFAULT installer,
-    // which must refuse rather than npx-install over the prod ~/.local/bin/iapeer.
+    // which must refuse rather than fetch+build over the prod ~/.local/bin/iapeer.
     expect(() =>
       updateIapeer({
         env: { IAPEER_TEST_SANDBOX: '1' },