@maadb/core 0.14.0 → 0.15.0

package/README.md

@@ -3,9 +3,9 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](package.json)
 [![TypeScript](https://img.shields.io/badge/typescript-strict-blue.svg)](tsconfig.json)
-[![Tests](https://img.shields.io/badge/tests-1225%20passing-brightgreen.svg)](tests)
+[![CI](https://github.com/maadb/maadb/actions/workflows/ci.yml/badge.svg)](https://github.com/maadb/maadb/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@maadb/core.svg)](https://www.npmjs.com/package/@maadb/core)
-[![Version](https://img.shields.io/badge/version-0.12.4-purple.svg)](Version.md)
+[![GitHub Release](https://img.shields.io/github/v/release/maadb/maadb?label=release)](https://github.com/maadb/maadb/releases/latest)
 
 > **Markdown is the database. The engine makes it queryable.**
 
@@ -15,7 +15,7 @@ MAADb stores records as markdown files with YAML frontmatter for structured fiel
 
 - **Markdown is canonical.** Open any record in any text editor — your data is exactly what's on screen, no translation layer.
 - **History policy is explicit.** Choose per-write audit commits, a Git-free feed, zero-write reads, batched commits, or annotated snapshots per project. `maad_history` shows available Git history.
-- **LLM-native.** Ships with 30+ MCP tools for discovery, read, write, maintenance, and auth. Designed for agent workflows from the start.
+- **LLM-native.** Ships with 46 MCP tools for discovery, read, write, maintenance, and auth. Designed for agent workflows from the start.
 - **Optional schemas.** Add YAML schemas when you want structure, skip them when you don't. Validation runs on writes, never on old records.
 - **The index is a speed layer.** SQLite stores pointers into your markdown files. Delete it and `maad reindex` rebuilds it from the markdown — your data never depends on the index surviving.
 - **Safe under concurrent writes.** Clean shutdown, lock recovery, rate limiting, retry-safe operations all built in.
@@ -279,7 +279,7 @@ Generate a token from the CLI (plaintext printed ONCE; server stores only the SH
 
 ```bash
 node dist/cli.js --instance /path/to/instance.yaml auth issue-token \
-  --role=admin --name='primary-gateway' --projects='*' --agent=agt-gateway
+  --role=admin --name='primary-gateway' --projects='*' --agent=gateway-agent
 # → maad_pat_<32hex> on stdout
 ```
 
@@ -320,7 +320,7 @@ rotating a token, discard the old session and initialize a fresh one with the ne
 bearer. A client that previously reused one session across several tokens must now
 open one session per token.
 
-> **Known gap (0.12.4):** `maad_instance_reload` does not reload `tokens.yaml`.
+> **Known gap (still present in v0.14.0):** `maad_instance_reload` does not reload `tokens.yaml`.
 > On a deployment where SIGHUP is unavailable, a revocation written to
 > `tokens.yaml` by another process is not observed by the running server until it
 > restarts, and sessions bound to the revoked token stay live until then. Prefer
@@ -369,7 +369,7 @@ my-project/
   _backend/                       # SQLite index — gitignored, rebuildable
     maad.db
   _import/                        # Drop zone for raw markdown imports
-  _skills/                        # Agent skill files (architect, import, etc.) — engine-managed
+  _skills/                        # Agent skill files (architect, import, graph, corpus, etc.) — engine-managed
   MAAD.md                         # Managed: canonical agent operating instructions (static, stamped)
   CLAUDE.md / AGENTS.md           # Created once at init: thin pointers to MAAD.md, user-owned after
   <type-dirs>/                    # Record files — one directory per type
@@ -429,9 +429,15 @@ The vector store is `sqlite-vec` (in the same SQLite file); the lexical leg is F
 
 ## Current state
 
-**Current:** v0.12.4 — HTTP MCP sessions bound to the authenticated principal that opened them: a session ID alone no longer reaches a session, and revoke, rotate, reload, and expiry tear down every session bound to the affected token.
+**Current:** v0.15.0 — managed graph-ontology and corpus-explorer skills teach agents typed-graph densification and unfamiliar-project mapping using existing MCP primitives (`maad_related`, `maad_relationship_paths`, `maad_join`, …).
+
+See the [v0.15.0 release notes](docs/releases/v0.15.0.md) for highlights, verification, and migration notes.
 
 Recent shipped scope:
+- **0.15.0** — Managed `_skills/graph-ontology.md` and `_skills/corpus-explorer.md` (MANAGED_ARTIFACTS 4 → 6)
+- **0.14.0** — Per-project `audit`, `feed`, `read`, `batch`, and `snapshot` history modes; explicit flush; crash recovery; history health telemetry
+- **0.13.0** — Evidence-backed relationship paths with deterministic bounded traversal and canonical edge evidence
+- **0.12.4** — HTTP sessions bound to the authenticated principal that opened them; revoke, rotate, reload, and expiry tear down affected sessions
 - **0.12.3** — Token-store `reload` serialized against in-flight mutations, so a SIGHUP during issue/revoke/rotate cannot drop a just-written token from the in-memory index
 - **0.12.2** — Canonical path containment for `maad_scan`; serialized token-store issue/revoke/rotate
 - **0.12.1** — Escape newlines and carriage returns in double-quoted YAML frontmatter scalars
@@ -450,7 +456,7 @@ See [Version.md](Version.md) for the full release history and forward plan.
 
 - TypeScript strict, Node.js 24+ (current Active LTS)
 - 6 production dependencies: `better-sqlite3`, `gray-matter`, `js-yaml`, `simple-git`, `@modelcontextprotocol/sdk`, `pino`. Plus one **optional** dependency `sqlite-vec` (semantic retrieval) — lazily loaded only when `MAAD_SEMANTIC_ENABLE` is on; absent or failed to load ⇒ semantic disabled, engine unaffected
-- 1225 tests, Vitest — run on every push/PR across Ubuntu and Windows
+- 1,274 tests at v0.15.0, Vitest — run on every push/PR across Ubuntu and Windows
 - MIT license, pre-1.0, actively developed
 
 ## License

package/dist/architect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"architect.d.ts","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"AAMA,wBAAgB,sBAAsB,IAAI,MAAM,CAwN/C"}
+{"version":3,"file":"architect.d.ts","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"AAMA,wBAAgB,sBAAsB,IAAI,MAAM,CA8N/C"}

package/dist/architect.js

@@ -118,6 +118,12 @@ For each entity, determine: master or transaction. Use the design checkpoint fro
 
 ### 2. Map relationships
 Draw the refs: what points to what. A job refs a customer and a technician. A note appends to a job.
+Name \`ref\` fields as relations (\`parent_case\`, \`assigned_attorney\`), not
+generics (\`link\`, \`related\`) — the field name is the only edge label the
+graph exposes. When an existing corpus has prose links that should become
+queryable structure, that is densification: add an optional \`ref\` field
+(additive evolution), then set it on records — see \`_skills/graph-ontology.md\`
+Recipe 4. Do not invent Cypher-style edges or UI graph views in the engine.
 
 ### 3. Define fields
 For each type: name, type, required, indexed, enum values, ref targets. Use domain knowledge for sensible defaults.

package/dist/architect.js.map

@@ -1 +1 @@
-{"version":3,"file":"architect.js","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2CAA2C;AAC3C,6EAA6E;AAC7E,2DAA2D;AAC3D,+EAA+E;AAE/E,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsNR,CAAC;AACF,CAAC"}
+{"version":3,"file":"architect.js","sourceRoot":"","sources":["../src/architect.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2CAA2C;AAC3C,6EAA6E;AAC7E,2DAA2D;AAC3D,+EAA+E;AAE/E,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4NR,CAAC;AACF,CAAC"}

package/dist/instructions/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/instructions/manifest.ts"],"names":[],"mappings":"AA+BA,iFAAiF;AACjF,wBAAgB,aAAa,IAAI,MAAM,CAOtC;AAED,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAKvD,CAAC;AAIF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAwB,GAAG,MAAM,CAElG;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI9D;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,gBAAgB,CAAC;IACxB,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,iBAAiB,CAUnG;AAWD,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAGrE;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrC,qEAAqE;IACrE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;IACtC,mCAAmC;IACnC,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,WAAW,CActF;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAW7E"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/instructions/manifest.ts"],"names":[],"mappings":"AAiCA,iFAAiF;AACjF,wBAAgB,aAAa,IAAI,MAAM,CAOtC;AAED,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAOvD,CAAC;AAIF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAwB,GAAG,MAAM,CAElG;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI9D;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,gBAAgB,CAAC;IACxB,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,iBAAiB,CAUnG;AAWD,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAGrE;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrC,qEAAqE;IACrE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;IACtC,mCAAmC;IACnC,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,WAAW,CActF;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAW7E"}

package/dist/instructions/manifest.js

@@ -25,6 +25,8 @@ import { createRequire } from 'node:module';
 import { generateMaadMd } from '../maad-md.js';
 import { generateSchemaGuide, generateImportGuide } from '../skill-files.js';
 import { generateArchitectSkill } from '../architect.js';
+import { generateGraphOntologySkill } from '../skills/graph-ontology.js';
+import { generateCorpusExplorerSkill } from '../skills/corpus-explorer.js';
 const require = createRequire(import.meta.url);
 /** Engine version = template version. Resolved from the shipped package.json. */
 export function engineVersion() {
@@ -46,6 +48,8 @@ export const MANAGED_ARTIFACTS = [
     { name: 'architect-core', relPath: '_skills/architect-core.md', generate: generateArchitectSkill },
     { name: 'schema-guide', relPath: '_skills/schema-guide.md', generate: generateSchemaGuide },
     { name: 'import-guide', relPath: '_skills/import-guide.md', generate: generateImportGuide },
+    { name: 'graph-ontology', relPath: '_skills/graph-ontology.md', generate: generateGraphOntologySkill },
+    { name: 'corpus-explorer', relPath: '_skills/corpus-explorer.md', generate: generateCorpusExplorerSkill },
 ];
 const STAMP_RE = /^<!-- maadb:managed name=([A-Za-z0-9_-]+) engine=([^\s]+) hash=sha256:([0-9a-f]{64}) -->\r?\n?/;
 export function hashBody(body) {

package/dist/instructions/manifest.js.map

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

package/dist/maad-md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maad-md.d.ts","sourceRoot":"","sources":["../src/maad-md.ts"],"names":[],"mappings":"AAUA,wBAAgB,cAAc,IAAI,MAAM,CAkHvC"}
+{"version":3,"file":"maad-md.d.ts","sourceRoot":"","sources":["../src/maad-md.ts"],"names":[],"mappings":"AAUA,wBAAgB,cAAc,IAAI,MAAM,CAoHvC"}

package/dist/maad-md.js

@@ -120,6 +120,8 @@ of secrets and personal data you would not hand to every project member.
 - \`_skills/architect-core.md\` — design and deploy schemas (Architect mode)
 - \`_skills/schema-guide.md\` — schema DSL reference and evolution
 - \`_skills/import-guide.md\` — importing existing data
+- \`_skills/graph-ontology.md\` — typed graph traversal and densification
+- \`_skills/corpus-explorer.md\` — map an unfamiliar project to a typed corpus map
 `;
 }
 //# sourceMappingURL=maad-md.js.map

package/dist/maad-md.js.map

@@ -1 +1 @@
-{"version":3,"file":"maad-md.js","sourceRoot":"","sources":["../src/maad-md.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,sEAAsE;AACtE,6EAA6E;AAC7E,wEAAwE;AACxE,oEAAoE;AACpE,+EAA+E;AAE/E,MAAM,UAAU,cAAc;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgHR,CAAC;AACF,CAAC"}
+{"version":3,"file":"maad-md.js","sourceRoot":"","sources":["../src/maad-md.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,sEAAsE;AACtE,6EAA6E;AAC7E,wEAAwE;AACxE,oEAAoE;AACpE,+EAA+E;AAE/E,MAAM,UAAU,cAAc;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHR,CAAC;AACF,CAAC"}

package/dist/skill-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-files.d.ts","sourceRoot":"","sources":["../src/skill-files.ts"],"names":[],"mappings":"AAKA,wBAAgB,mBAAmB,IAAI,MAAM,CAgP5C;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAmK5C"}
+{"version":3,"file":"skill-files.d.ts","sourceRoot":"","sources":["../src/skill-files.ts"],"names":[],"mappings":"AAKA,wBAAgB,mBAAmB,IAAI,MAAM,CAwP5C;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAmK5C"}

package/dist/skill-files.js

@@ -212,6 +212,14 @@ client:
   target: client    # points to records of type "client"
 \`\`\`
 
+**Densification (additive refs):** when agents discover structural links that
+only exist in prose or \`mention\` annotations, prefer adding a new *optional*
+\`ref\` (or \`list\` of \`ref\`) field to the current schema version, \`maad_reload\`,
+then set the field on records. That is an additive change — no \`vN+1\` bump.
+Name the field as a relation, set \`index: true\` if you will filter or join on
+it, and verify with \`maad_find_orphans\`. Full recipe:
+\`_skills/graph-ontology.md\`.
+
 ## Template headings (optional)
 
 Add heading structure that \`maad_create\` will generate for new records:

package/dist/skill-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-files.js","sourceRoot":"","sources":["../src/skill-files.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2DAA2D;AAC3D,oDAAoD;AACpD,+EAA+E;AAE/E,MAAM,UAAU,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8OR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiKR,CAAC;AACF,CAAC"}
+{"version":3,"file":"skill-files.js","sourceRoot":"","sources":["../src/skill-files.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2DAA2D;AAC3D,oDAAoD;AACpD,+EAA+E;AAE/E,MAAM,UAAU,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsPR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiKR,CAAC;AACF,CAAC"}

package/dist/skills/corpus-explorer.d.ts

@@ -0,0 +1,2 @@
+export declare function generateCorpusExplorerSkill(): string;
+//# sourceMappingURL=corpus-explorer.d.ts.map

package/dist/skills/corpus-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-explorer.d.ts","sourceRoot":"","sources":["../../src/skills/corpus-explorer.ts"],"names":[],"mappings":"AAIA,wBAAgB,2BAA2B,IAAI,MAAM,CAuNpD"}

package/dist/skills/corpus-explorer.js

@@ -0,0 +1,220 @@
+// ============================================================================
+// Corpus Explorer skill — managed instruction generator (fully static).
+// ============================================================================
+export function generateCorpusExplorerSkill() {
+    return `# Mapping an Unfamiliar Project
+
+> Managed by the MAADb engine — do not edit (changes block future refreshes).
+> Project-specific corpus maps belong in \`_skills/local/corpus-map.md\`.
+> Never append session notes to this skill file.
+
+## Purpose
+
+You are an agent landing in a MAADB project you did not build and do not
+know. This skill is a staged exploration protocol that takes you from zero
+to a **written, typed map of the corpus** — what the record types are, how
+they connect, how dense the graph is, where it is broken — using cheap,
+bounded reads. The protocol front-loads index-backed tools and defers
+full-body reads to the end, so orientation cost stays flat even on large
+corpora.
+
+Audience: any agent with reader access. The final stage writes one overlay
+file, which needs writer access (skippable — report the map in chat instead).
+
+## When to load this skill
+
+- First session in a project whose \`maad_summary\` you have never seen.
+- You've been handed a task referencing types or records you can't place.
+- Before proposing schema or convention changes to an inherited corpus —
+  map first, judge second.
+- Periodically on long-lived projects, to refresh a stale corpus map.
+
+If \`maad_summary\` shows an **empty** project, stop — this skill maps
+existing data. Enter Architect mode instead (\`_skills/architect-core.md\`).
+
+## Ground rules
+
+- **Never** map a corpus by listing or reading files directly — all reads go
+  through MCP tools, and the index is faster than you.
+- Match read shape to need (\`hot\` → fields, \`warm\` → one section, \`cold\` →
+  full body). In this protocol, \`cold\` appears only in Stage 3, on a
+  handful of records.
+- Everything you write into the map must be grounded in a tool result from
+  **this** session; counts you intend to publish go through
+  \`maad_verify mode=count\` first.
+- Watch \`_meta.warnings[]\` on every response — orientation is exactly when
+  you want to notice degraded subsystems or drift signals early.
+
+## The protocol
+
+Six stages. Each produces a section of the final map; you can stop early
+and still hold a partial map (that's a feature — Stage 6 records what was
+*not* explored, and a truncated map that says so is still trustworthy).
+
+### Stage 0 — Bind and capabilities
+
+On multi-project servers: \`maad_projects\`, then \`maad_use_project\` (bindings
+are fixed per session). Then \`maad_describe\`: project overview, stats, and
+\`capabilities\` — notably whether relationship paths and semantic search are
+available in this deployment, which decides your Stage 4 toolkit.
+
+### Stage 1 — Summary: the shape
+
+\`maad_summary\` once. Extract into notes:
+
+- Type inventory with counts — your candidate class list.
+- Sample doc IDs per type — seeds for Stages 3–4.
+- Warnings: broken refs and validation errors reported here are your first
+  hygiene signal; carry them to Stage 5, don't chase them yet.
+
+Skim \`MAAD.md\` and list \`_skills/\` — an existing \`_skills/local/\` overlay
+(prior conventions, an earlier corpus map) changes your job from *mapping*
+to *verifying and updating a map*.
+
+### Stage 2 — Schema: the intended graph
+
+For each type from Stage 1: \`maad_schema <type>\`. Build two tables as you
+go:
+
+1. **Type table** — required fields, enums (the project's controlled
+   vocabularies), indexed fields (what the project's builders expected to
+   query — intent fossilized in config).
+2. **Edge table** — every \`ref\` / \`list[ref]\` field: source type, field
+   name, target type. This is the **intended** graph, before you've looked
+   at a single record.
+
+Note the file-strategy signal: types whose records are few but block-heavy
+are transaction-pattern (entries appended under parents — see
+\`_skills/schema-guide.md\`); their real "record count" is blocks, not files,
+and their parent ref is usually the corpus's highest-volume edge.
+
+### Stage 3 — Samples: the actual records
+
+Per type, cheapest first:
+
+- \`maad_get <sample-id> hot\` on 1–2 samples — do real records fill the
+  schema's fields? Sparse optional fields here foreshadow a sparse graph.
+- \`maad_query\` with a projection of 3–4 key fields, small limit — the
+  spread, not just the sample (status distributions, date ranges).
+- \`maad_get <id> cold\` on **one or two** records total, for narrative
+  texture: are bodies annotated (\`[[type:value|label]]\`)? Do they name
+  other records in prose?
+- \`maad_search primitive=entity limit=20\` (then other primitives that the
+  domain suggests) — is the annotation layer in active use, and with which
+  subtypes? Remember frontmatter string fields index as \`primitive=entity,
+  subtype=<field-name>\`, so search results mix field values and body
+  annotations; the subtype tells you which.
+- Where \`maad_describe\` said semantic search is enabled,
+  \`maad_semantic_search\` with 2–3 domain phrases is a cheap probe for
+  themes the schema doesn't capture. Degraded responses say so — fall back
+  without guessing.
+
+### Stage 4 — Related and paths: the realized graph
+
+Now compare the intended graph (Stage 2) with reality.
+
+1. **Measure edge usage with aggregates, not iteration.** For each edge in
+   the Stage 2 table: \`maad_aggregate docType=<source> groupBy=<ref-field>\`.
+   Group count ≈ how many distinct targets are actually referenced; a
+   near-empty result means a declared-but-unused edge. This also hands you
+   the **hubs** — target IDs with the largest groups.
+2. **Walk the hubs.** For the top 2–3 hubs: \`maad_related direction=both\`,
+   then
+
+   \`\`\`
+   maad_relationship_paths
+     startDocId: <hub>
+     direction: both
+     maxDepth: 2
+   \`\`\`
+
+   Organize by \`nodes[].distance\`. Check \`truncation.truncated\` /
+   \`limitsReached\` before concluding anything about reach — a truncated
+   traversal is a lower bound.
+3. **Probe the observed-vs-intended gap.** Re-run one hub's paths with
+   \`extractionKinds: ["ref", "mention"]\`. Many \`mention\` edges beyond the
+   \`ref\` edges = structure living in prose = densification opportunity
+   (that's the graph/ontology skill's Recipe 4 — record it, don't fix it
+   mid-mapping). Few mentions *and* few refs on a corpus whose bodies
+   clearly name other records (Stage 3) = links invisible to tooling
+   entirely; note that too.
+4. Cross-type detail questions that surface here ("which open cases belong
+   to which client industry?") are \`maad_join\` / ref-chain
+   \`maad_aggregate\` one-liners — use them to spot-check, resist per-record
+   loops.
+
+### Stage 5 — Integrity: where the graph is broken
+
+- \`maad_find_orphans\` — per-record broken-ref inventory (which ref fields
+  point at nonexistent targets).
+- \`maad_verify mode=integrity\` — the wider sweep (index/document drift,
+  schema drift) — cheap insurance that what you just mapped is what's
+  actually on disk, especially if the project sees external edits.
+
+Findings go **in the map**, not into ad-hoc repair: repair tools follow
+dry-run-then-confirm contracts and deserve a deliberate pass, and on
+read-only deployments mutation isn't yours to do (\`READ_ONLY\` — report,
+don't retry).
+
+### Stage 6 — Write the typed map
+
+Deliverable: \`_skills/local/corpus-map.md\` — a project-owned overlay file
+(engine refresh never touches it). Create or update; if one existed
+(Stage 1), preserve its history notes and update the snapshot. Suggested
+shape:
+
+\`\`\`markdown
+# Corpus Map — <project> (as of <date>)
+
+## Types
+| type | count* | pattern | purpose (one line) | key fields |
+
+## Edges (intended vs realized)
+| ref field | source → target | declared | usage (aggregate) | mention overflow? |
+
+## Annotation practice
+Primitives/subtypes in active use; whether doc-ID mentions are annotated.
+
+## Hubs
+Top hub records and what clusters around them (path-walk findings).
+
+## Hygiene
+Broken refs / orphans / drift found in Stage 5. Unfixed — inventory only.
+
+## Not explored
+Types sampled shallowly, truncated traversals, stages skipped.
+
+## Open questions
+Anything the corpus couldn't answer about itself.
+
+*counts verified via maad_verify mode=count on <date>
+\`\`\`
+
+The map is a **snapshot of project truth, owned by the project** — exactly
+what \`_skills/local/\` is for. It is not engine documentation; never put
+engine-version facts in it (they rot — \`MAAD.md\` owns those).
+
+If you lack writer access, deliver the same content as your session report.
+
+## After the map — handoffs
+
+- Sparse realized graph, rich mention/prose links → load the
+  graph/ontology skill (\`_skills/graph-ontology.md\`) and run its
+  densification recipe against the map's "mention overflow" column.
+- Schema gaps or evolution needs → Architect mode
+  (\`_skills/architect-core.md\` + \`_skills/schema-guide.md\`).
+- Broken refs / drift → a deliberate hygiene pass with the repair tools'
+  dry-run contracts; the map's Hygiene section is its worklist.
+
+## Non-goals / hand off to the host
+
+- No visualization: the map is markdown tables. Rendering it as an
+  interactive graph or dashboard is host-side work — never engine core.
+- No repair during mapping — inventory only (Stage 5).
+- No schema edits during mapping — the map may *recommend*; Architect
+  executes.
+- No file-system spelunking — if a question can't be answered through the
+  tool surface, that inability is itself a finding for the map.
+`;
+}
+//# sourceMappingURL=corpus-explorer.js.map

package/dist/skills/corpus-explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-explorer.js","sourceRoot":"","sources":["../../src/skills/corpus-explorer.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAE/E,MAAM,UAAU,2BAA2B;IACzC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqNR,CAAC;AACF,CAAC"}

package/dist/skills/graph-ontology.d.ts

@@ -0,0 +1,2 @@
+export declare function generateGraphOntologySkill(): string;
+//# sourceMappingURL=graph-ontology.d.ts.map

package/dist/skills/graph-ontology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-ontology.d.ts","sourceRoot":"","sources":["../../src/skills/graph-ontology.ts"],"names":[],"mappings":"AAIA,wBAAgB,0BAA0B,IAAI,MAAM,CAuPnD"}

package/dist/skills/graph-ontology.js

@@ -0,0 +1,252 @@
+// ============================================================================
+// Graph / Ontology skill — managed instruction generator (fully static).
+// ============================================================================
+export function generateGraphOntologySkill() {
+    return `# Working the Project as a Typed Graph
+
+> Managed by the MAADb engine — do not edit (changes block future refreshes).
+> Project-specific ontology conventions belong in \`_skills/local/ontology.md\`.
+> Findings and densification notes go there too — never append them to this file.
+
+## Purpose
+
+You are an agent operating on a MAADB project. This skill teaches you to
+treat the project as a **typed information graph**: to read structure that
+already exists, to choose the right traversal tool for each question, and to
+**densify** the graph — promoting links that live only in prose into typed,
+queryable structure. The engine gives you bounded graph primitives; you are
+the query planner and the ontologist.
+
+Audience: any agent with at least reader access. Densification recipes
+(Recipes 4–5) additionally need writer access and — for schema changes — the
+Architect channel described in \`_skills/architect-core.md\`.
+
+## When to load this skill
+
+- You need to answer connection questions: "how is X related to Y?",
+  "what depends on this record?", "walk the chain from case to industry."
+- You are building a report or view that spans record types.
+- You notice the project is **link-poor**: records reference each other in
+  body text but \`maad_related\` returns little — structure exists in prose
+  but not in the graph.
+- You are establishing or extending naming/linking conventions for a project
+  (light ontology work).
+
+For first-contact orientation in a project you don't know at all, load
+\`_skills/corpus-explorer.md\` first — it ends where this skill begins.
+
+## The graph model — what an edge is
+
+The engine derives edges from markdown; SQLite rows are derived data and
+reindex rebuilds them. There are exactly two edge kinds:
+
+1. **\`ref\` edges** — frontmatter fields of type \`ref\` (or \`list\` with
+   \`item_type: ref\`). Typed by the **field name** (\`client\`, \`parent_case\`,
+   \`assigned_attorney\`). This is the *intentional* graph: schema-declared,
+   validated, queryable, joinable. Evidence origin is the field; source
+   line/block evidence is null.
+2. **\`mention\` edges** — inline annotations \`[[type:value|label]]\` whose
+   value is a doc ID with a registered prefix (e.g.
+   \`[[identifier:cli-001|the client]]\`). This is the *observed* graph:
+   extracted from prose, carrying line and block evidence, but not schema-
+   validated. Plain prose that names a record without an annotation creates
+   **no edge at all**.
+
+The density gradient — prose → annotated mention → typed ref — is the core
+of this skill. Each promotion step makes a link more queryable and more
+verifiable.
+
+## Choosing the traversal tool
+
+| Question shape | Tool | Why |
+|---|---|---|
+| "What touches this one record?" (1 hop) | \`maad_related\` | Cheapest neighborhood read; direction \`outgoing\` / \`incoming\` / \`both\` (default \`both\`) |
+| "How does A connect to B?" / "what's within N hops?" / "show me the evidence" | \`maad_relationship_paths\` | Bounded multi-hop BFS, deterministic, cycle-safe, returns per-edge evidence and per-node distance |
+| "Give me these fields from many records *and* their ref targets" | \`maad_join\` | One call instead of query → get → get (N+1) chains |
+| "Roll up a metric across a ref hop" ("cases per client industry") | \`maad_aggregate\` with a ref-chain \`groupBy\` (\`"client->industry"\`) | Group-by resolves refs at query time; never iterate records to count |
+| "Where is this record *mentioned* in prose?" | \`maad_search\` (scoped \`value=<docId>\`) or \`maad_relationship_paths\` with \`extractionKinds: ["ref","mention"]\` | Mentions are opt-in on path traversal; search finds the raw extracted objects |
+
+Two defaults that will bite you if unexamined:
+
+- \`maad_related\` defaults to direction \`both\`; \`maad_relationship_paths\`
+  defaults to \`outgoing\`. When a path result looks mysteriously empty, check
+  direction first — dependency questions ("what refs this?") need
+  \`incoming\` or \`both\`.
+- \`maad_relationship_paths\` traverses **\`ref\` edges only by default**.
+  Mentions are opt-in via \`extractionKinds: ["ref", "mention"]\`. If you are
+  probing the *observed* graph, you must opt in.
+
+Bounds (validated, over-cap values are rejected, not clamped): \`maxDepth\`
+default 2, cap 4 · \`maxNodes\` 50/100 · \`maxEdges\` 100/200 · \`maxPaths\`
+25/50. If a response trips the byte-size guard, narrow with \`fieldLabels\`
+or \`extractionKinds\`, or lower the limits — don't retry as-is.
+
+## Recipes
+
+### Recipe 1 — Typed neighborhood of one record
+
+Goal: everything structurally connected to \`cas-012\`, with meaning.
+
+1. \`maad_get cas-012 hot\` — its own typed fields.
+2. \`maad_related docId=cas-012 direction=both\` — 1-hop adjacency; note the
+   **field names** on each edge (they are your edge types).
+3. Where you need target detail for several neighbors of the same type,
+   don't loop \`maad_get\` — use \`maad_join\` on the source type with
+   \`refFields\` (Recipe 6).
+4. Only escalate to \`maad_relationship_paths\` if 1 hop is insufficient.
+
+### Recipe 2 — Connection between two specific records
+
+Goal: does \`cas-012\` connect to \`con-007\`, and through what?
+
+\`\`\`
+maad_relationship_paths
+  startDocId: cas-012
+  targetDocId: con-007
+  direction: both
+  maxDepth: 3
+\`\`\`
+
+Read the result as claims with proof: each edge carries \`fieldLabel\`,
+extraction kind, and canonical evidence (source line + block for mentions;
+field origin for refs). When you report the connection, cite the doc IDs on
+the path — and for mention-backed hops, treat the link as *observed, not
+validated* and say so.
+
+A \`state: missing\` node on a path is a **broken ref** — the edge exists but
+the target doesn't. Report it (and see Recipe 7); missing targets are
+terminal, so real connectivity may be wider than what a broken hop shows.
+
+### Recipe 3 — Bounded exploration outward from a hub
+
+Goal: the working set within 2 hops of a central record.
+
+\`\`\`
+maad_relationship_paths
+  startDocId: cli-001
+  direction: both
+  maxDepth: 2
+  fieldLabels: [client, parent_case]     # optional: only these edge types
+\`\`\`
+
+Use \`nodes[].distance\` to organize the result into rings. Check
+\`truncation.truncated\` and \`limitsReached\` **before** summarizing — a
+truncated traversal is a lower bound, not a census, and your summary must
+say which limit was hit if one was.
+
+### Recipe 4 — Promote prose links to typed structure (densification)
+
+Goal: links that exist only in narrative become schema-typed refs.
+
+1. **Find candidates.** Probe the observed graph:
+   \`maad_relationship_paths\` from key records with
+   \`extractionKinds: ["ref","mention"]\`, \`maxDepth: 1\` — every \`mention\`
+   edge is a candidate. Corpus-wide, \`maad_search\` with \`value=<docId>\`
+   scoped per hub record inventories where it's mentioned. (Prose links with
+   no annotation at all are invisible to tools — surfacing those is judgment
+   work while reading \`cold\` bodies.)
+2. **Decide if the link is structural.** Promote when the relationship is:
+   queried or filtered on; needed in joins/aggregates; integrity-relevant
+   (should break loudly if the target vanishes); or cardinality-stable
+   (every case has a client). Leave as mention/prose when it's incidental
+   commentary.
+3. **Type it.** If a suitable \`ref\` field exists in the schema, done. If
+   not, this is a schema change — an **additive** new \`ref\` field (with
+   \`target\` and \`index: true\`) via the Architect channel
+   (\`_skills/architect-core.md\`): registry/schema edits go through the
+   deployment's approved channel, then \`maad_reload\`. Never write schema
+   files through record tools.
+4. **Set the field.** \`maad_update\` per record (sequential; pass
+   \`expectedVersion\` when you hold a read), or \`maad_bulk_update\` for a
+   genuine batch. Keep the prose mention — you are adding structure, not
+   rewriting narrative.
+5. **Verify.** \`maad_related\` on a sample now shows the edge with the new
+   field label; \`maad_find_orphans docType=<type>\` catches typo'd targets
+   immediately.
+6. **Record the convention** in \`_skills/local/ontology.md\` (Recipe 5) so
+   the next agent types new records the same way.
+
+### Recipe 5 — Light ontology, MAADB-style
+
+An ontology here is **conventions, not a reasoner**:
+
+- **Classes** = registered doc types.
+- **Typed predicates** = \`ref\` field names. Name them as relations
+  (\`parent_case\`, \`assigned_attorney\`), not generically (\`link1\`, \`related\`).
+  The field name is the only edge label the graph has — spend it well.
+- **Controlled vocabularies** = \`enum\` fields.
+- **Annotation vocabulary** = the 11 fixed primitives plus registry
+  \`extraction.subtypes\` (e.g. \`attorney: entity\`). Subtypes make
+  \`maad_search\` domain-aware without engine changes.
+
+The ontology's *documentation* lives in \`_skills/local/ontology.md\` — a
+project-owned overlay file you create and maintain (it survives engine
+refreshes). Keep it short and normative: one table of types, one table of
+ref fields with their meaning and cardinality, the subtype vocabulary, and
+the annotation policy ("always annotate doc-ID mentions in prose as
+\`[[identifier:<docId>|label]]\`" is the single highest-leverage rule, because
+it feeds Recipe 4's candidate pipeline).
+
+Schema *changes* implied by ontology work are Architect work — hand off to
+\`_skills/architect-core.md\`; do not duplicate its channel rules here.
+
+### Recipe 6 — Cross-type reports and views
+
+Row-level view ("open cases with client name and industry"):
+
+\`\`\`
+maad_join
+  docType: case
+  filters: { status: open }
+  refs: [client]
+  fields: [title, status, opened_at]
+  refFields: { client: [name, industry] }
+\`\`\`
+
+Rollup ("case count by client industry"):
+
+\`\`\`
+maad_aggregate
+  docType: case
+  groupBy: "client->industry"
+  filters: { status: open }
+\`\`\`
+
+Compose the two into a markdown report (summary table from \`aggregate\`,
+detail table from \`join\`) and — if the report should persist — write it as a
+record via \`maad_create\` in a report-ish doc type if the project has one.
+Ground every number you state: \`maad_verify mode=count\` (or \`mode=field\`)
+before presenting totals as fact. Rendering to anything richer than
+markdown, and publishing anywhere, is host work (see Non-goals).
+
+### Recipe 7 — Graph hygiene
+
+Run before *and* after densification passes:
+
+- \`maad_find_orphans\` — records whose ref fields point at nonexistent
+  targets (broken refs, per-record detail).
+- \`maad_verify mode=integrity\` — the broader sweep (index drift, schema
+  drift, broken refs) after pulls or external edits.
+- \`maad_validate\` after any schema evolution — see \`_skills/schema-guide.md\`
+  § versioning for the migrate-or-grandfather discipline.
+
+A densification pass that introduces broken refs has made the graph *worse*
+— typed-but-wrong beats untyped only if you catch it, which is why Recipe 4
+ends in \`maad_find_orphans\`.
+
+## Non-goals / hand off to the host
+
+- **No visualization here.** Emitting a small inline Mermaid/DOT sketch in
+  chat from path output is fine as ordinary agent output; anything
+  interactive, rendered, served, or saved as an artifact belongs to
+  host-side skills — never to \`@maadb/core\`.
+- **No query language.** You compose bounded primitives; there is no Cypher
+  and none is coming.
+- **No inference engine.** Do not invent transitive/derived edges and
+  present them as data — a multi-hop path is evidence of connection, not a
+  new fact. If a derived relationship matters, promote it explicitly
+  (Recipe 4) so it becomes a real, validated edge.
+- **No schema writes through record tools** — Architect channel only.
+`;
+}
+//# sourceMappingURL=graph-ontology.js.map

package/dist/skills/graph-ontology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-ontology.js","sourceRoot":"","sources":["../../src/skills/graph-ontology.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,yEAAyE;AACzE,+EAA+E;AAE/E,MAAM,UAAU,0BAA0B;IACxC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqPR,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maadb/core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Markdown As A Database — treats markdown as the canonical data store, builds a queryable index, and gives LLMs deterministic read/write access.",
   "repository": {
     "type": "git",
@@ -48,10 +48,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "better-sqlite3": "12.11.1",
     "gray-matter": "~4.0.3",
-    "js-yaml": "~4.3.0",
+    "js-yaml": "~4.3.1",
     "pino": "10.3.1",
     "simple-git": "3.36.0"
   },