aimeat 1.40.1 → 2.0.0

package/dist/src/mcp/appdev-pitfalls.js

@@ -0,0 +1,208 @@
+/**
+ * @file appdev-pitfalls.ts
+ * @description MCP tools for the LEARNED appdev-pitfall knowledge base — what AI builders
+ *   learn while building apps ON AIMEAT, model-attributed and owner-scoped with per-entry
+ *   opt-in platform sharing. Entries live in the reserved knowledge package
+ *   `appdev-pitfalls` (keys packages/appdev-pitfalls/{category}/{slug}) so the generic
+ *   aimeat_knowledge_* tools can read them too. The LIST tool merges three sources by scope:
+ *   own learned entries, the curated registry (data/appdev-pitfalls.ts), and other owners'
+ *   public-shared entries. Model attribution is MANDATORY per entry and INDICATIVE only.
+ * @structure registerAppdevPitfallTools() — aimeat_appdev_pitfall_report / _list / _delete
+ * @usage registerAppdevPitfallTools(mcp, storage, config, () => agentGaii, emitResourceUpdated);
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — initial (AppDev KB Phase 4): report=upsert (+status outdated,
+ *     +share→public), paginated merged list with facets, delete with manifest cleanup.
+ */
+import { z } from 'zod';
+import { annotationsFor } from './annotations.js';
+import { descriptionFor } from './catalog/shape.js';
+import { getAppdevPitfalls } from '../data/appdev-pitfalls.js';
+import { PITFALL_PACKAGE_ID, PITFALL_PREFIX, PITFALL_MANIFEST_KEY, PITFALL_SLUG_RE, slugifyKb, listOwnerScopeMemory as kbListOwnerScope, ownIdentitySet as kbOwnIdentitySet, findOwnEntry as kbFindOwnEntry, upsertPitfallManifest, } from '../services/appdev-kb.js';
+export { PITFALL_PACKAGE_ID };
+const SEVERITIES = ['info', 'warn', 'critical'];
+const SEV_RANK = { critical: 0, warn: 1, info: 2 };
+function slugify(s) { return slugifyKb(s); }
+function asIndexEntry(source, rec) {
+    const v = rec.value;
+    return {
+        source,
+        key: rec.key,
+        title: v?.title ?? rec.key,
+        category: v?.category ?? null,
+        slug: v?.slug ?? null,
+        model: v?.model ?? null,
+        applies_to: v?.applies_to ?? [],
+        severity: v?.severity ?? 'warn',
+        status: v?.status ?? 'active',
+        updated: v?.updated ?? rec.updatedAt,
+        shared: rec.visibility === 'public',
+    };
+}
+export function registerAppdevPitfallTools(mcp, storage, config, getAgentGaii, emitResourceUpdated) {
+    const agentGaii = getAgentGaii();
+    const listOwnerScopeMemory = (opts) => kbListOwnerScope(storage, config, agentGaii, opts);
+    const ownIdentitySet = () => kbOwnIdentitySet(storage, config, agentGaii);
+    const findOwnEntry = (key) => kbFindOwnEntry(storage, config, agentGaii, key);
+    const upsertManifest = (entryKey, title, remove = false) => upsertPitfallManifest(storage, config, agentGaii, entryKey, title, remove);
+    // ── aimeat_appdev_pitfall_report — upsert one learned pitfall ──
+    mcp.tool('aimeat_appdev_pitfall_report', descriptionFor('aimeat_appdev_pitfall_report'), {
+        model: z.string().min(1).max(64).describe('REQUIRED: YOUR OWN model id — the model that hit/solved this (e.g. claude-fable-5, kimi-k2.7-code). Self-identify from your own configuration, never ask the user. Indicative attribution'),
+        category: z.string().min(1).max(40).describe('Kebab-case category, e.g. auth, ext, cortex, realtime, mobile, publish, ai, data'),
+        title: z.string().min(3).max(160).describe('Short imperative title of the pitfall'),
+        symptom: z.string().min(5).max(2000).describe('What the builder observes when hitting it'),
+        resolution: z.string().min(5).max(4000).describe('What to do instead — the better way'),
+        slug: z.string().max(64).optional().describe('Stable kebab-case slug; same {category, slug} UPDATES the entry (better wording replaces old). Derived from the title when omitted'),
+        applies_to: z.array(z.string().max(20)).max(8).optional().describe('Areas this applies to (app, auth, ext, cortex, iam, realtime, ai, mobile, publish)'),
+        severity: z.enum(SEVERITIES).optional().describe('Default warn'),
+        status: z.enum(['active', 'outdated']).optional().describe('Mark outdated when models no longer stumble on it (kept, hidden from default lists)'),
+        app_ref: z.string().max(200).optional().describe('Related app, e.g. owner/filename.html'),
+        share: z.boolean().optional().describe('true = publish this entry platform-wide (public visibility) so other owners\' agents learn from it; default = private to your owner scope'),
+    }, annotationsFor('aimeat_appdev_pitfall_report'), async ({ model, category, title, symptom, resolution, slug, applies_to, severity, status, app_ref, share }) => {
+        const cat = slugify(category);
+        const slg = slug ? slug.toLowerCase() : slugify(title);
+        if (!PITFALL_SLUG_RE.test(cat) || !PITFALL_SLUG_RE.test(slg)) {
+            return { content: [{ type: 'text', text: 'Invalid category/slug — use kebab-case (a-z, 0-9, dashes)' }], isError: true };
+        }
+        const key = `${PITFALL_PREFIX}${cat}/${slg}`;
+        const now = new Date().toISOString();
+        const existing = await findOwnEntry(key);
+        const normModel = model.trim().toLowerCase();
+        const value = {
+            title, symptom, resolution,
+            model: normModel,
+            category: cat, slug: slg,
+            applies_to: (applies_to ?? []).map(a => a.toLowerCase()),
+            severity: severity ?? 'warn',
+            status: status ?? 'active',
+            ...(app_ref ? { app_ref } : {}),
+            reported_by: agentGaii,
+            created: existing?.value?.created ?? now,
+            updated: now,
+        };
+        const visibility = share === true ? 'public' : share === false ? 'owner' : (existing?.visibility ?? 'owner');
+        const tags = ['knowledge-entry', 'pitfall', `model:${normModel}`, ...value.applies_to.map(a => `applies:${a}`)];
+        await storage.setMemory({
+            key,
+            ownerGaii: existing?.ownerGaii ?? agentGaii,
+            value,
+            visibility,
+            tags,
+            ttlHours: null,
+            version: (existing?.version ?? 0) + 1,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        });
+        await upsertManifest(key, title);
+        emitResourceUpdated(agentGaii, `aimeat://knowledge/${PITFALL_PACKAGE_ID}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        key, category: cat, slug: slg,
+                        updated: !!existing, version: (existing?.version ?? 0) + 1,
+                        visibility, shared: visibility === 'public',
+                    }, null, 2),
+                }],
+        };
+    });
+    // ── aimeat_appdev_pitfall_list — merged, paginated, faceted ──
+    mcp.tool('aimeat_appdev_pitfall_list', descriptionFor('aimeat_appdev_pitfall_list'), {
+        scope: z.enum(['own', 'platform', 'all']).optional().describe('own = your owner bubble; platform = curated registry + other owners\' shared entries; all = both (default)'),
+        category: z.string().max(40).optional(),
+        model: z.string().max(64).optional().describe('Filter learned entries to one model (e.g. claude-haiku-4.5)'),
+        applies_to: z.string().max(20).optional().describe('Filter by area (app, auth, ext, cortex, iam, realtime, ai, mobile, publish)'),
+        status: z.enum(['active', 'outdated', 'all']).optional().describe('Default active (outdated hidden)'),
+        limit: z.number().int().min(1).max(100).optional().describe('Page size, default 25'),
+        offset: z.number().int().min(0).optional().describe('Page start, default 0'),
+    }, annotationsFor('aimeat_appdev_pitfall_list'), async ({ scope, category, model, applies_to, status, limit, offset }) => {
+        const effScope = scope ?? 'all';
+        const wantStatus = status ?? 'active';
+        const normModel = model?.trim().toLowerCase();
+        const entries = [];
+        if (effScope === 'own' || effScope === 'all') {
+            const own = await listOwnerScopeMemory({ prefix: PITFALL_PREFIX, tags: ['pitfall'] });
+            for (const rec of own) {
+                if (rec.key === PITFALL_MANIFEST_KEY)
+                    continue;
+                entries.push(asIndexEntry('learned', rec));
+            }
+        }
+        if (effScope === 'platform' || effScope === 'all') {
+            // Curated node registry — platform-level knowledge, always available.
+            for (const p of getAppdevPitfalls({ includeOutdated: wantStatus !== 'active' })) {
+                entries.push({
+                    source: 'curated', id: p.id, title: p.title, category: null, slug: p.id,
+                    model: null, applies_to: p.appliesTo, severity: p.severity,
+                    status: p.status ?? 'active', updated: p.updatedAt, shared: true,
+                    detail_url: `/v1/appdev/pitfalls/${p.id}`,
+                });
+            }
+            // Other owners' public-shared learned entries.
+            const ownIds = await ownIdentitySet();
+            const { items } = await storage.listAllMemory({ prefix: PITFALL_PREFIX, visibility: 'public', limit: 500 });
+            for (const rec of items) {
+                if (rec.key === PITFALL_MANIFEST_KEY)
+                    continue;
+                if (ownIds.has(rec.ownerGaii))
+                    continue; // own entries come from the own branch
+                if (!(rec.tags ?? []).includes('pitfall'))
+                    continue;
+                entries.push(asIndexEntry('learned-shared', rec));
+            }
+        }
+        let filtered = entries;
+        if (wantStatus !== 'all')
+            filtered = filtered.filter(e => e.status === wantStatus);
+        if (category)
+            filtered = filtered.filter(e => e.category === slugify(category) || e.id === category);
+        if (normModel)
+            filtered = filtered.filter(e => e.model === null || e.model === normModel);
+        if (applies_to)
+            filtered = filtered.filter(e => e.applies_to.includes(applies_to.toLowerCase()));
+        filtered.sort((a, b) => {
+            const s = (SEV_RANK[a.severity] ?? 1) - (SEV_RANK[b.severity] ?? 1);
+            if (s !== 0)
+                return s;
+            return String(b.updated ?? '').localeCompare(String(a.updated ?? ''));
+        });
+        const facets = { category: {}, model: {}, source: {} };
+        for (const e of filtered) {
+            const c = e.category ?? '(curated)';
+            facets.category[c] = (facets.category[c] ?? 0) + 1;
+            if (e.model)
+                facets.model[e.model] = (facets.model[e.model] ?? 0) + 1;
+            facets.source[e.source] = (facets.source[e.source] ?? 0) + 1;
+        }
+        const lim = limit ?? 25;
+        const off = offset ?? 0;
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        pitfalls: filtered.slice(off, off + lim),
+                        total: filtered.length,
+                        offset: off,
+                        limit: lim,
+                        facets,
+                        hint: 'Full learned entries: aimeat_knowledge_get package_id=appdev-pitfalls. Curated detail: GET /v1/appdev/pitfalls/{id}.',
+                    }, null, 2),
+                }],
+        };
+    });
+    // ── aimeat_appdev_pitfall_delete — remove one learned entry (+manifest ref) ──
+    mcp.tool('aimeat_appdev_pitfall_delete', descriptionFor('aimeat_appdev_pitfall_delete'), {
+        category: z.string().min(1).max(40),
+        slug: z.string().min(1).max(64),
+    }, annotationsFor('aimeat_appdev_pitfall_delete'), async ({ category, slug }) => {
+        const key = `${PITFALL_PREFIX}${slugify(category)}/${slug.toLowerCase()}`;
+        const existing = await findOwnEntry(key);
+        if (!existing) {
+            return { content: [{ type: 'text', text: `Pitfall entry not found: ${key}` }], isError: true };
+        }
+        await storage.deleteMemory(existing.ownerGaii, key);
+        await upsertManifest(key, '', true);
+        emitResourceUpdated(agentGaii, `aimeat://knowledge/${PITFALL_PACKAGE_ID}`);
+        return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, key }, null, 2) }] };
+    });
+}
+//# sourceMappingURL=appdev-pitfalls.js.map

package/dist/src/mcp/appdev-pitfalls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appdev-pitfalls.js","sourceRoot":"","sources":["../../../src/mcp/appdev-pitfalls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EACH,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,eAAe,EAAE,SAAS,EACpF,oBAAoB,IAAI,gBAAgB,EAAE,cAAc,IAAI,gBAAgB,EAC5E,YAAY,IAAI,cAAc,EAAE,qBAAqB,GAExD,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AACzD,MAAM,QAAQ,GAA2B,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAI3E,SAAS,OAAO,CAAC,CAAS,IAAY,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5D,SAAS,YAAY,CAAC,MAAoC,EAAE,GAAiB;IACzE,MAAM,CAAC,GAAG,GAAG,CAAC,KAA0C,CAAC;IACzD,OAAO;QACH,MAAM;QACN,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,GAAG,CAAC,GAAG;QAC1B,QAAQ,EAAE,CAAC,EAAE,QAAQ,IAAI,IAAI;QAC7B,IAAI,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI;QACrB,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,IAAI;QACvB,UAAU,EAAE,CAAC,EAAE,UAAU,IAAI,EAAE;QAC/B,QAAQ,EAAE,CAAC,EAAE,QAAQ,IAAI,MAAM;QAC/B,MAAM,EAAE,CAAC,EAAE,MAAM,IAAI,QAAQ;QAC7B,OAAO,EAAE,CAAC,EAAE,OAAO,IAAI,GAAG,CAAC,SAAS;QACpC,MAAM,EAAE,GAAG,CAAC,UAAU,KAAK,QAAQ;KACtC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,0BAA0B,CACtC,GAAc,EACd,OAAgB,EAChB,MAAoB,EACpB,YAA0B,EAC1B,mBAA6D;IAE7D,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,MAAM,oBAAoB,GAAG,CAAC,IAA0C,EAAE,EAAE,CACxE,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACvD,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAC1E,MAAM,YAAY,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;IACtF,MAAM,cAAc,GAAG,CAAC,QAAgB,EAAE,KAAa,EAAE,MAAM,GAAG,KAAK,EAAE,EAAE,CACvE,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAE/E,kEAAkE;IAClE,GAAG,CAAC,IAAI,CACJ,8BAA8B,EAC9B,cAAc,CAAC,8BAA8B,CAAC,EAC9C;QACI,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,2LAA2L,CAAC;QACtO,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,kFAAkF,CAAC;QAChI,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,uCAAuC,CAAC;QACnF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;QAC1F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QACvF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oIAAoI,CAAC;QAClL,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oFAAoF,CAAC;QACxJ,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;QAChE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qFAAqF,CAAC;QACjJ,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;QACzF,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2IAA2I,CAAC;KACtL,EACD,cAAc,CAAC,8BAA8B,CAAC,EAC9C,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE;QAC1G,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,2DAA2D,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACtI,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,cAAc,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE7C,MAAM,KAAK,GAAsB;YAC7B,KAAK,EAAE,OAAO,EAAE,UAAU;YAC1B,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG;YACxB,UAAU,EAAE,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;YACxD,QAAQ,EAAE,QAAQ,IAAI,MAAM;YAC5B,MAAM,EAAE,MAAM,IAAI,QAAQ;YAC1B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,WAAW,EAAE,SAAS;YACtB,OAAO,EAAG,QAAQ,EAAE,KAAkC,EAAE,OAAO,IAAI,GAAG;YACtE,OAAO,EAAE,GAAG;SACf,CAAC;QACF,MAAM,UAAU,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,IAAI,OAAO,CAAC,CAAC;QAC7G,MAAM,IAAI,GAAG,CAAC,iBAAiB,EAAE,SAAS,EAAE,SAAS,SAAS,EAAE,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;QAEhH,MAAM,OAAO,CAAC,SAAS,CAAC;YACpB,GAAG;YACH,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,SAAS;YAC3C,KAAK;YACL,UAAU;YACV,IAAI;YACJ,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC;YACrC,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,GAAG;YACrC,SAAS,EAAE,GAAG;SACjB,CAAC,CAAC;QACH,MAAM,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,mBAAmB,CAAC,SAAS,EAAE,sBAAsB,kBAAkB,EAAE,CAAC,CAAC;QAE3E,OAAO;YACH,OAAO,EAAE,CAAC;oBACN,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACjB,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG;wBAC7B,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC;wBAC1D,UAAU,EAAE,MAAM,EAAE,UAAU,KAAK,QAAQ;qBAC9C,EAAE,IAAI,EAAE,CAAC,CAAC;iBACd,CAAC;SACL,CAAC;IACN,CAAC,CACJ,CAAC;IAEF,gEAAgE;IAChE,GAAG,CAAC,IAAI,CACJ,4BAA4B,EAC5B,cAAc,CAAC,4BAA4B,CAAC,EAC5C;QACI,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4GAA4G,CAAC;QAC3K,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;QACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6DAA6D,CAAC;QAC5G,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6EAA6E,CAAC;QACjI,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;QACrG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACpF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;KAC/E,EACD,cAAc,CAAC,4BAA4B,CAAC,EAC5C,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;QACpE,MAAM,QAAQ,GAAG,KAAK,IAAI,KAAK,CAAC;QAChC,MAAM,UAAU,GAAG,MAAM,IAAI,QAAQ,CAAC;QACtC,MAAM,SAAS,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAmC,EAAE,CAAC;QAEnD,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YAC3C,MAAM,GAAG,GAAG,MAAM,oBAAoB,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACtF,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;gBACpB,IAAI,GAAG,CAAC,GAAG,KAAK,oBAAoB;oBAAE,SAAS;gBAC/C,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;YAC/C,CAAC;QACL,CAAC;QACD,IAAI,QAAQ,KAAK,UAAU,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YAChD,sEAAsE;YACtE,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,EAAE,eAAe,EAAE,UAAU,KAAK,QAAQ,EAAE,CAAC,EAAE,CAAC;gBAC9E,OAAO,CAAC,IAAI,CAAC;oBACT,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;oBACvE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBAC1D,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI;oBAChE,UAAU,EAAE,uBAAuB,CAAC,CAAC,EAAE,EAAE;iBAC5C,CAAC,CAAC;YACP,CAAC;YACD,+CAA+C;YAC/C,MAAM,MAAM,GAAG,MAAM,cAAc,EAAE,CAAC;YACtC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YAC5G,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;gBACtB,IAAI,GAAG,CAAC,GAAG,KAAK,oBAAoB;oBAAE,SAAS;gBAC/C,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;oBAAE,SAAS,CAAC,uCAAuC;gBAChF,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;oBAAE,SAAS;gBACpD,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC;YACtD,CAAC;QACL,CAAC;QAED,IAAI,QAAQ,GAAG,OAAO,CAAC;QACvB,IAAI,UAAU,KAAK,KAAK;YAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;QACnF,IAAI,QAAQ;YAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC;QACrG,IAAI,SAAS;YAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;QAC1F,IAAI,UAAU;YAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAE,CAAC,CAAC,UAAuB,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAE/G,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAkB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;YACxF,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,CAAC;YACtB,OAAO,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAwG,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QAC5J,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACvB,MAAM,CAAC,GAAI,CAAC,CAAC,QAA0B,IAAI,WAAW,CAAC;YACvD,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACnD,IAAI,CAAC,CAAC,KAAK;gBAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAe,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAe,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1F,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACrF,CAAC;QAED,MAAM,GAAG,GAAG,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC;QACxB,OAAO;YACH,OAAO,EAAE,CAAC;oBACN,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACjB,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC;wBACxC,KAAK,EAAE,QAAQ,CAAC,MAAM;wBACtB,MAAM,EAAE,GAAG;wBACX,KAAK,EAAE,GAAG;wBACV,MAAM;wBACN,IAAI,EAAE,sHAAsH;qBAC/H,EAAE,IAAI,EAAE,CAAC,CAAC;iBACd,CAAC;SACL,CAAC;IACN,CAAC,CACJ,CAAC;IAEF,gFAAgF;IAChF,GAAG,CAAC,IAAI,CACJ,8BAA8B,EAC9B,cAAc,CAAC,8BAA8B,CAAC,EAC9C;QACI,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;KAClC,EACD,cAAc,CAAC,8BAA8B,CAAC,EAC9C,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE;QACzB,MAAM,GAAG,GAAG,GAAG,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QAC1E,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,4BAA4B,GAAG,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC5G,CAAC;QACD,MAAM,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACpD,MAAM,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACpC,mBAAmB,CAAC,SAAS,EAAE,sBAAsB,kBAAkB,EAAE,CAAC,CAAC;QAC3E,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC3G,CAAC,CACJ,CAAC;AACN,CAAC"}

package/dist/src/mcp/appdev-proofs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file appdev-proofs.ts
+ * @description aimeat_appdev_proof_attach — self-reported acceleration proofs on community
+ *   contributions (AppDev KB Phase 8): a per-model pass/fail run record attached to either a
+ *   community library pack (append-only public memory record `libpack.proofs.{packId}`, owner
+ *   of the cortex only) or one of the caller's own app-template proposals (appended to the
+ *   manifest's proofs array). Every v1 proof carries selfReported: true — this is attribution
+ *   toward "proven acceleration", never a node-verified audit (that badge is a later additive
+ *   field). Mirrors the curated PackProof ledger contract: append-only, duplicate
+ *   (model, testSet, date) rejected.
+ * @structure registerAppdevProofTools()
+ * @usage registerAppdevProofTools(mcp, storage, config, () => agentGaii);
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — initial (AppDev KB Phase 8).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AimeatConfig } from '../config.js';
+import type { Storage } from '../storage/interface.js';
+export declare const packProofsKey: (packId: string) => string;
+export declare function registerAppdevProofTools(mcp: McpServer, storage: Storage, config: AimeatConfig, getAgentGaii: () => string): void;
+//# sourceMappingURL=appdev-proofs.d.ts.map

package/dist/src/mcp/appdev-proofs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appdev-proofs.d.ts","sourceRoot":"","sources":["../../../src/mcp/appdev-proofs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAQvD,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,MAAoC,CAAC;AAEpF,wBAAgB,wBAAwB,CACpC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,MAAM,MAAM,GAC3B,IAAI,CA0FN"}

package/dist/src/mcp/appdev-proofs.js

@@ -0,0 +1,103 @@
+/**
+ * @file appdev-proofs.ts
+ * @description aimeat_appdev_proof_attach — self-reported acceleration proofs on community
+ *   contributions (AppDev KB Phase 8): a per-model pass/fail run record attached to either a
+ *   community library pack (append-only public memory record `libpack.proofs.{packId}`, owner
+ *   of the cortex only) or one of the caller's own app-template proposals (appended to the
+ *   manifest's proofs array). Every v1 proof carries selfReported: true — this is attribution
+ *   toward "proven acceleration", never a node-verified audit (that badge is a later additive
+ *   field). Mirrors the curated PackProof ledger contract: append-only, duplicate
+ *   (model, testSet, date) rejected.
+ * @structure registerAppdevProofTools()
+ * @usage registerAppdevProofTools(mcp, storage, config, () => agentGaii);
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — initial (AppDev KB Phase 8).
+ */
+import { z } from 'zod';
+import { parseGAII } from '../utils/gaii.js';
+import { annotationsFor } from './annotations.js';
+import { descriptionFor } from './catalog/shape.js';
+import { getTemplateProposal, templateProposalKey } from '../services/app-template-proposals.js';
+export const packProofsKey = (packId) => `libpack.proofs.${packId}`;
+export function registerAppdevProofTools(mcp, storage, config, getAgentGaii) {
+    const agentGaii = getAgentGaii();
+    mcp.tool('aimeat_appdev_proof_attach', descriptionFor('aimeat_appdev_proof_attach'), {
+        subject_type: z.enum(['library_pack', 'app_template']).describe('library_pack = a COMMUNITY pack you own (your public cortex lib); app_template = one of your template proposals'),
+        subject_id: z.string().min(1).max(80).describe('The community pack id (cortex name) or template proposal id'),
+        model: z.string().min(1).max(64).describe('REQUIRED: model the run was made with (indicative, self-reported)'),
+        verdict: z.enum(['pass', 'fail']).describe('Did the pack/template accelerate the run — honest fails make passes credible'),
+        evidence: z.string().min(3).max(500).describe('URL or node storage/memory ref pointing at the run evidence'),
+        test_set: z.string().max(120).optional().describe('Repeatable test-set/spec identifier, when one was used'),
+        tokens: z.number().int().min(0).optional().describe('Output tokens the run consumed, when known'),
+    }, annotationsFor('aimeat_appdev_proof_attach'), async ({ subject_type, subject_id, model, verdict, evidence, test_set, tokens }) => {
+        const parsed = parseGAII(agentGaii);
+        const owner = parsed?.owner ?? (agentGaii.includes('@') && !agentGaii.includes('#') ? agentGaii.split('@')[0] : null);
+        if (!owner)
+            return { content: [{ type: 'text', text: 'Could not resolve the caller to an owner' }], isError: true };
+        const ownerGhii = `${owner}@${config.nodeId}`;
+        const now = new Date().toISOString();
+        const proof = {
+            model: model.trim().toLowerCase(),
+            verdict,
+            evidence,
+            ...(test_set ? { testSet: test_set } : {}),
+            ...(typeof tokens === 'number' ? { tokens } : {}),
+            date: now.slice(0, 10),
+            selfReported: true,
+        };
+        const isDup = (list) => list.some(p => p.model === proof.model && (p.testSet ?? '') === (proof.testSet ?? '') && p.date === proof.date);
+        if (subject_type === 'library_pack') {
+            // Owner gate: the community pack is the caller's own ACTIVE + PUBLIC cortex with a lib.
+            const all = await storage.listCortexExtensions({ status: 'active' });
+            const ext = all.find(e => e.name === subject_id);
+            if (!ext || ext.visibility !== 'public' || !ext.components.some(c => c.type === 'lib')) {
+                return { content: [{ type: 'text', text: `No active public community pack "${subject_id}"` }], isError: true };
+            }
+            if (ext.installedBy !== owner) {
+                return { content: [{ type: 'text', text: 'Only the pack owner may attach proofs to it' }], isError: true };
+            }
+            const key = packProofsKey(subject_id);
+            const existing = await storage.getMemory(ownerGhii, key);
+            const value = (existing?.value ?? { packId: subject_id, proofs: [] });
+            const proofs = Array.isArray(value.proofs) ? value.proofs : [];
+            if (isDup(proofs)) {
+                return { content: [{ type: 'text', text: 'Duplicate proof (same model + test set + date) — the ledger is append-only, one entry per run' }], isError: true };
+            }
+            proofs.push(proof);
+            await storage.setMemory({
+                key,
+                ownerGaii: ownerGhii,
+                value: { packId: subject_id, proofs },
+                visibility: 'public',
+                tags: ['libpack-proofs'],
+                ttlHours: null,
+                version: (existing?.version ?? 0) + 1,
+                createdAt: existing?.createdAt ?? now,
+                updatedAt: now,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify({ attached: true, subject_type, subject_id, proofs_total: proofs.length, self_reported: true }, null, 2) }] };
+        }
+        // app_template: append to the caller's own proposal manifest.
+        const found = await getTemplateProposal(storage, config, agentGaii, subject_id);
+        if (!found) {
+            return { content: [{ type: 'text', text: `Template proposal not found: ${subject_id}` }], isError: true };
+        }
+        const manifest = found.manifest;
+        const proofs = Array.isArray(manifest.proofs) ? manifest.proofs : [];
+        if (isDup(proofs)) {
+            return { content: [{ type: 'text', text: 'Duplicate proof (same model + test set + date) — the ledger is append-only, one entry per run' }], isError: true };
+        }
+        proofs.push(proof);
+        manifest.proofs = proofs;
+        manifest.updatedAt = now;
+        await storage.setMemory({
+            ...found.record,
+            key: templateProposalKey(subject_id),
+            value: manifest,
+            version: (found.record.version ?? 0) + 1,
+            updatedAt: now,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify({ attached: true, subject_type, subject_id, proofs_total: proofs.length, self_reported: true }, null, 2) }] };
+    });
+}
+//# sourceMappingURL=appdev-proofs.js.map

package/dist/src/mcp/appdev-proofs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appdev-proofs.js","sourceRoot":"","sources":["../../../src/mcp/appdev-proofs.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/appdev-research.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file appdev-research.ts
+ * @description MCP research surface for building apps ON AIMEAT: aimeat_appdev_overview —
+ *   the one call an agent makes BEFORE framing a build. Returns compact indexes (owner's
+ *   apps, library packs with per-model proofs, T1/T2/T3 templates, skills, curated +
+ *   learned pitfalls, template proposals) with drill-down pointers; calls the service
+ *   directly (no HTTP hop).
+ * @structure registerAppdevResearchTools() — aimeat_appdev_overview
+ * @usage registerAppdevResearchTools(mcp, storage, config, () => agentGaii);
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — initial (AppDev KB Phase 5).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AimeatConfig } from '../config.js';
+import type { Storage } from '../storage/interface.js';
+export declare function registerAppdevResearchTools(mcp: McpServer, storage: Storage, config: AimeatConfig, getAgentGaii: () => string): void;
+//# sourceMappingURL=appdev-research.d.ts.map

package/dist/src/mcp/appdev-research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appdev-research.d.ts","sourceRoot":"","sources":["../../../src/mcp/appdev-research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAKvD,wBAAgB,2BAA2B,CACvC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,MAAM,MAAM,GAC3B,IAAI,CAgBN"}

package/dist/src/mcp/appdev-research.js

@@ -0,0 +1,27 @@
+/**
+ * @file appdev-research.ts
+ * @description MCP research surface for building apps ON AIMEAT: aimeat_appdev_overview —
+ *   the one call an agent makes BEFORE framing a build. Returns compact indexes (owner's
+ *   apps, library packs with per-model proofs, T1/T2/T3 templates, skills, curated +
+ *   learned pitfalls, template proposals) with drill-down pointers; calls the service
+ *   directly (no HTTP hop).
+ * @structure registerAppdevResearchTools() — aimeat_appdev_overview
+ * @usage registerAppdevResearchTools(mcp, storage, config, () => agentGaii);
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — initial (AppDev KB Phase 5).
+ */
+import { z } from 'zod';
+import { annotationsFor } from './annotations.js';
+import { descriptionFor } from './catalog/shape.js';
+import { buildAppdevOverview, OVERVIEW_SECTIONS } from '../services/appdev-overview.js';
+export function registerAppdevResearchTools(mcp, storage, config, getAgentGaii) {
+    const agentGaii = getAgentGaii();
+    mcp.tool('aimeat_appdev_overview', descriptionFor('aimeat_appdev_overview'), {
+        model: z.string().max(64).optional().describe('Your OWN model id (e.g. claude-fable-5, kimi-k2.7-code) — self-identify from your own configuration, never ask the user. Marks packs proven for it and filters learned pitfalls. Indicative'),
+        sections: z.array(z.enum(OVERVIEW_SECTIONS)).optional().describe('Subset of sections to fetch (default all): apps, library_packs, app_templates, skills, pitfalls_curated, pitfalls_learned, template_proposals'),
+    }, annotationsFor('aimeat_appdev_overview'), async ({ model, sections }) => {
+        const overview = await buildAppdevOverview(storage, config, agentGaii, { model, sections });
+        return { content: [{ type: 'text', text: JSON.stringify(overview, null, 2) }] };
+    });
+}
+//# sourceMappingURL=appdev-research.js.map

package/dist/src/mcp/appdev-research.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appdev-research.js","sourceRoot":"","sources":["../../../src/mcp/appdev-research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAExF,MAAM,UAAU,2BAA2B,CACvC,GAAc,EACd,OAAgB,EAChB,MAAoB,EACpB,YAA0B;IAE1B,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,GAAG,CAAC,IAAI,CACJ,wBAAwB,EACxB,cAAc,CAAC,wBAAwB,CAAC,EACxC;QACI,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6LAA6L,CAAC;QAC5O,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+IAA+I,CAAC;KACpN,EACD,cAAc,CAAC,wBAAwB,CAAC,EACxC,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5F,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC7F,CAAC,CACJ,CAAC;AACN,CAAC"}

package/dist/src/mcp/apps.d.ts

@@ -9,6 +9,7 @@
  *   import { registerAppsTools } from './apps.js';
  *   registerAppsTools(mcp, storage, config, getAgentGaii, emitResourceUpdated, emitResourceListChanged);
  * @version-history
+ *   2026-07-19 — publish/draft_publish next_steps nudge (face+bound-skills+template hint, best-effort) (AppDev KB Phase 6)
  *   v1.0.0 — 2026-05-02 — Initial creation: 5 tools for app publish, list, get, delete, versions
  *   v1.1.0 -- 2026-05-29 -- Add tool annotations (title + read/destructive/idempotent/openWorld hints)
  *     from shared annotations.ts for Connectors Directory compliance.
@@ -18,6 +19,11 @@
  *   v1.4.0 -- 2026-07-07 -- Add aimeat_app_fork (sanctioned, provenance-recording fork behind the
  *     forkable/paid gates); publish carries the forkable flag forward; list/get surface forkable +
  *     forked_from.
+ *   v1.5.0 -- 2026-07-16 -- aimeat_app_list metrics via 2 batch queries (getAppDownloadsForApps +
+ *     countAppForksForApps), was getAppDownloads + countAppForks PER app (Phase 3).
+ *   v1.6.0 -- 2026-07-16 -- Agent-Bundled Apps Slice 1: aimeat_app_publish accepts cortex_agents
+ *     (declarative crew-defs → manifest.cortex.agents), validated fail-loud; carried forward on
+ *     update + draft save when omitted.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AimeatConfig } from '../config.js';

package/dist/src/mcp/apps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../../src/mcp/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,yBAAyB,CAAC;AAQpE,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,MAAM,MAAM,EAC1B,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,EAC7D,uBAAuB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACrD,IAAI,CAklBN"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../../src/mcp/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,yBAAyB,CAAC;AAWpE,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,MAAM,MAAM,EAC1B,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,EAC7D,uBAAuB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACrD,IAAI,CA+nBN"}

package/dist/src/mcp/apps.js

@@ -9,6 +9,7 @@
  *   import { registerAppsTools } from './apps.js';
  *   registerAppsTools(mcp, storage, config, getAgentGaii, emitResourceUpdated, emitResourceListChanged);
  * @version-history
+ *   2026-07-19 — publish/draft_publish next_steps nudge (face+bound-skills+template hint, best-effort) (AppDev KB Phase 6)
  *   v1.0.0 — 2026-05-02 — Initial creation: 5 tools for app publish, list, get, delete, versions
  *   v1.1.0 -- 2026-05-29 -- Add tool annotations (title + read/destructive/idempotent/openWorld hints)
  *     from shared annotations.ts for Connectors Directory compliance.
@@ -18,15 +19,42 @@
  *   v1.4.0 -- 2026-07-07 -- Add aimeat_app_fork (sanctioned, provenance-recording fork behind the
  *     forkable/paid gates); publish carries the forkable flag forward; list/get surface forkable +
  *     forked_from.
+ *   v1.5.0 -- 2026-07-16 -- aimeat_app_list metrics via 2 batch queries (getAppDownloadsForApps +
+ *     countAppForksForApps), was getAppDownloads + countAppForks PER app (Phase 3).
+ *   v1.6.0 -- 2026-07-16 -- Agent-Bundled Apps Slice 1: aimeat_app_publish accepts cortex_agents
+ *     (declarative crew-defs → manifest.cortex.agents), validated fail-loud; carried forward on
+ *     update + draft save when omitted.
  */
 import { z } from 'zod';
 import { parseGAII } from '../utils/gaii.js';
 import { logger } from '../utils/logger.js';
 import { generateUploadToken } from '../services/upload-token.js';
 import { generateDraftToken } from '../services/draft-token.js';
+import { validateCortexAgents } from '../models/crew-def-schemas.js';
 import { annotationsFor } from './annotations.js';
 import { descriptionFor } from './catalog/shape.js';
+import { agentFaceKey } from '../services/agent-face.js';
+import { listSkillsByBinding } from '../services/skills.js';
 export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResourceUpdated, emitResourceListChanged) {
+    // Post-publish reflection nudge (AppDev KB Phase 6): report whether the app already has an
+    // agent face + bound skills, and hint at proposing a template. Best-effort — a publish must
+    // NEVER fail because this enrichment does.
+    async function buildNextSteps(ownerGaii, ownerName, filename) {
+        try {
+            const [faceRec, boundSkills] = await Promise.all([
+                storage.getMemory(ownerGaii, agentFaceKey(filename)).catch(() => null),
+                listSkillsByBinding(storage, config, `app:${ownerName}/${filename}`, { ownerName }).catch(() => []),
+            ]);
+            return {
+                agent_face_present: !!faceRec,
+                bound_skills_count: boundSkills.length,
+                template_proposal_hint: 'If anything here generalizes, record it: aimeat_app_template_propose (with your model id). Finish checklist: agent face published, a skill bound (metadata.binding app:owner/filename), learnings reported via aimeat_appdev_pitfall_report.',
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
     // ── Tool 1: aimeat_app_publish ──
     mcp.tool('aimeat_app_publish', descriptionFor('aimeat_app_publish'), {
         filename: z.string().describe('App filename (e.g. "starwars.html"). Alphanumeric, dots, hyphens, underscores. Max 100 chars.'),
@@ -37,7 +65,8 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
         tags: z.array(z.string()).optional().describe('Array of tags for search/filtering'),
         icon: z.string().optional().describe('Emoji icon for the app'),
         version: z.string().optional().describe('Semver display version (e.g. "1.0.0"). Auto-generated if omitted.'),
-    }, annotationsFor('aimeat_app_publish'), async ({ filename, content_base64, name, description, category, tags, icon, version }) => {
+        cortex_agents: z.array(z.record(z.string(), z.unknown())).optional().describe('Declarative crew-defs this app ships (Agent-Bundled Apps). Each entry is a crewaimeat crew_def JSON document (agent_name, agents[], tasks[], ...) validated at publish — DATA the owner\'s own fleet interprets, never code. Stored as manifest.cortex.agents. Omit on update to carry the existing list forward; send [] to clear.'),
+    }, annotationsFor('aimeat_app_publish'), async ({ filename, content_base64, name, description, category, tags, icon, version, cortex_agents }) => {
         const agentGaii = getAgentGaii();
         const parsed = parseGAII(agentGaii);
         if (!parsed) {
@@ -104,6 +133,16 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
                 };
             }
         }
+        // Agent-Bundled Apps: validate declared crew-defs fail-loud — a malformed
+        // agents[] rejects the publish so it never reaches a fleet. Mirrors POST /v1/apps.
+        let cortexAgents;
+        if (cortex_agents !== undefined) {
+            const check = validateCortexAgents(cortex_agents);
+            if (!check.ok) {
+                return { content: [{ type: 'text', text: `Invalid cortex_agents (crew-def validation failed):\n${check.errors.join('\n')}` }], isError: true };
+            }
+            cortexAgents = check.agents;
+        }
         const manifest = {
             name,
             description: effectiveDescription,
@@ -115,6 +154,8 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
         };
         if (icon)
             manifest.icon = icon;
+        if (cortexAgents !== undefined && cortexAgents.length > 0)
+            manifest.cortex = { agents: cortexAgents };
         // Carry the parked + forkable + copy-protection state forward across
         // re-publishes (an update never silently re-exposes a parked app, flips fork
         // permission, or drops the owner's copy-protection). Mirrors POST /v1/apps.
@@ -126,6 +167,11 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
             forkableState = !!existingApp?.forkable;
             if (existingApp?.manifest?.protection)
                 manifest.protection = existingApp.manifest.protection;
+            // cortex.agents carried forward when omitted (an update never silently drops
+            // the app's bundled agents); an explicit [] clears the section.
+            if (cortex_agents === undefined && existingApp?.manifest?.cortex?.agents?.length) {
+                manifest.cortex = existingApp.manifest.cortex;
+            }
         }
         try {
             await storage.createApp({
@@ -156,6 +202,7 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
                             is_update: isUpdate,
                             download_url: downloadUrl,
                             inline_url: `${downloadUrl}?mode=inline`,
+                            next_steps: await buildNextSteps(ownerGaii, parsed.owner, filename),
                         }, null, 2),
                     }],
             };
@@ -206,6 +253,8 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
             manifest.icon = icon ?? base?.icon;
         if (base?.protection)
             manifest.protection = base.protection;
+        if (base?.cortex?.agents?.length)
+            manifest.cortex = base.cortex;
         try {
             await storage.saveAppDraft({
                 ownerGaii, ownerName: parsed.owner, filename, manifest,
@@ -276,6 +325,7 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
                             filename, version_number: newVersion, is_update: isUpdate,
                             parked: parkedState, download_url: downloadUrl, inline_url: `${downloadUrl}?mode=inline`,
                             note: 'Draft published as the new live version; the draft slot is cleared.',
+                            next_steps: await buildNextSteps(ownerGaii, parsed.owner, filename),
                         }, null, 2),
                     }],
             };
@@ -319,9 +369,14 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
             ...(own ? { ownerGaii: ownerGhii } : {}),
         };
         const { apps, total } = await storage.listApps(opts);
-        const result = await Promise.all(apps.map(async (app) => {
-            const downloads = await storage.getAppDownloads(app.ownerGaii, app.filename);
-            const forks = await storage.countAppForks(app.ownerGaii, app.filename);
+        // Per-app metrics in TWO batch queries (was getAppDownloads + countAppForks PER app = 2N).
+        const refs = apps.map(a => ({ ownerGaii: a.ownerGaii, filename: a.filename }));
+        const downloadsByApp = await storage.getAppDownloadsForApps(refs);
+        const forksByApp = await storage.countAppForksForApps(refs);
+        const result = apps.map((app) => {
+            const metricKey = `${app.ownerGaii} ${app.filename}`;
+            const downloads = downloadsByApp[metricKey] ?? 0;
+            const forks = forksByApp[metricKey] ?? 0;
             return {
                 owner: app.ownerName,
                 filename: app.filename,
@@ -340,7 +395,7 @@ export function registerAppsTools(mcp, storage, config, getAgentGaii, emitResour
                 download_url: `/v1/apps/${encodeURIComponent(app.ownerName)}/${encodeURIComponent(app.filename)}`,
                 created_at: app.createdAt,
             };
-        }));
+        });
         return {
             content: [{
                     type: 'text',