@agentproto/lesson 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @agentproto/lesson
+
+AIP-11 `LESSON.md` reference implementation. A markdown format for storing the transferable lessons an agent extracts from successful and failed runs — title, trigger, evidence, outcome — and a contract for how runtimes distill them and inject them back into future turns.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-11>
+
+## Usage
+
+```ts
+import { defineLesson } from "@agentproto/lesson"
+
+const x = defineLesson({
+  id: "my-lesson",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-JGP7TCUI.mjs

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/lesson v0.1.0-alpha
+ * AIP-11 LESSON.md `defineLesson` reference implementation.
+ */
+
+var lessonFrontmatterSchema = z.object({ "schema": z.literal("learning/v1").describe("Spec identifier. Must be the literal string 'learning/v1'."), "slug": z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$")).min(2).max(80).describe("Machine identifier, also the filename. Lowercase, digits, dashes. Imperative voice recommended."), "title": z.string().min(1).max(200).describe("One-sentence imperative title \u2014 what to do or avoid."), "trigger": z.object({ "description": z.string().min(1).max(1e3).describe("Plain-text description of when this lesson applies."), "tags": z.array(z.string().regex(new RegExp("^[a-z][a-z0-9-]*$"))).max(12).describe("Retrieval keywords. Keep narrow; three is usually enough.").default([]), "targets": z.array(z.object({ "operator": z.string().optional(), "role": z.string().optional(), "skill": z.string().optional() }).strict()).describe("Operator / role / skill globs that scope retrieval. Empty means anyone.").default([]), "metadata": z.record(z.string(), z.any()).describe("Vendor-specific trigger predicates. Standard fields above MUST NOT be redefined here.").default({}) }).strict(), "outcome": z.enum(["success", "failure", "mixed"]).describe("Whether the source run succeeded, failed, or the lesson is conditional across runs."), "evidence": z.array(z.object({ "kind": z.enum(["run", "conversation", "work-item", "audit", "wiki-page"]).describe("What the evidence reference points to. 'audit' = AIP-7 governance record."), "ref": z.string().min(1).max(256).describe("Opaque id or path the host can resolve. Never free text."), "note": z.string().max(500).describe("One-line factual note about the event \u2014 not the lesson.").optional() }).strict()).min(1).describe("Provenance \u2014 at least one evidence entry MUST resolve to a real run, conversation, work item, audit, or wiki page in the host's indices."), "confidence": z.number().gte(0).lte(1).describe("Author's confidence in [0,1]. Default 0.5 at first sighting. Runtimes weigh this against observed counts.").default(0.5), "success_count": z.number().int().gte(0).describe("Times the lesson 'worked' when applied. Maintained by the runtime; author-supplied values are initial only.").default(0), "failure_count": z.number().int().gte(0).describe("Times the lesson's claim was contradicted. Maintained by the runtime; author-supplied values are initial only.").default(0), "supersedes": z.array(z.string().regex(new RegExp("^[a-z][a-z0-9-]*[a-z0-9]$"))).describe("Slugs of lessons this lesson replaces. Supersession is explicit, never silent. Each cited slug MUST exist on disk.").default([]), "expires_at": z.string().datetime({ offset: true }).describe("Soft TTL (ISO 8601). Past this instant, retrieval treats the lesson as absent by default.").optional(), "metadata": z.record(z.string(), z.any()).describe("Vendor-specific extensions under namespaced keys (metadata.<vendor>.<field>). Standard fields MUST NOT be redefined.").default({}) }).strict().and(z.any()).describe("Validates the YAML frontmatter portion of an AIP-11 LESSON.md file \u2014 one transferable lesson distilled from a completed run.");
+var defineLesson = createDoctype({
+  aip: 11,
+  name: "lesson",
+  readIdentity: (def) => def.slug,
+  readDescription: (def) => def.title,
+  validate(def) {
+    const result = lessonFrontmatterSchema.safeParse(def);
+    if (!result.success) {
+      throw new Error(
+        `defineLesson (AIP-11): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    return { ...def };
+  }
+});
+
+export { defineLesson, lessonFrontmatterSchema };
+//# sourceMappingURL=chunk-JGP7TCUI.mjs.map
+//# sourceMappingURL=chunk-JGP7TCUI.mjs.map

package/dist/chunk-JGP7TCUI.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-lesson.ts"],"names":[],"mappings":"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","file":"chunk-JGP7TCUI.mjs","sourcesContent":["/**\n * AIP-11 LESSON.md frontmatter zod schema.\n *\n * Generated from `resources/aip-11/draft/LESSON.schema.json` via\n * json-schema-to-zod. Imported by both `define-lesson.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-lesson.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const lessonFrontmatterSchema = z.object({ \"schema\": z.literal(\"learning/v1\").describe(\"Spec identifier. Must be the literal string 'learning/v1'.\"), \"slug\": z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\")).min(2).max(80).describe(\"Machine identifier, also the filename. Lowercase, digits, dashes. Imperative voice recommended.\"), \"title\": z.string().min(1).max(200).describe(\"One-sentence imperative title — what to do or avoid.\"), \"trigger\": z.object({ \"description\": z.string().min(1).max(1000).describe(\"Plain-text description of when this lesson applies.\"), \"tags\": z.array(z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*$\"))).max(12).describe(\"Retrieval keywords. Keep narrow; three is usually enough.\").default([]), \"targets\": z.array(z.object({ \"operator\": z.string().optional(), \"role\": z.string().optional(), \"skill\": z.string().optional() }).strict()).describe(\"Operator / role / skill globs that scope retrieval. Empty means anyone.\").default([]), \"metadata\": z.record(z.string(), z.any()).describe(\"Vendor-specific trigger predicates. Standard fields above MUST NOT be redefined here.\").default({}) }).strict(), \"outcome\": z.enum([\"success\",\"failure\",\"mixed\"]).describe(\"Whether the source run succeeded, failed, or the lesson is conditional across runs.\"), \"evidence\": z.array(z.object({ \"kind\": z.enum([\"run\",\"conversation\",\"work-item\",\"audit\",\"wiki-page\"]).describe(\"What the evidence reference points to. 'audit' = AIP-7 governance record.\"), \"ref\": z.string().min(1).max(256).describe(\"Opaque id or path the host can resolve. Never free text.\"), \"note\": z.string().max(500).describe(\"One-line factual note about the event — not the lesson.\").optional() }).strict()).min(1).describe(\"Provenance — at least one evidence entry MUST resolve to a real run, conversation, work item, audit, or wiki page in the host's indices.\"), \"confidence\": z.number().gte(0).lte(1).describe(\"Author's confidence in [0,1]. Default 0.5 at first sighting. Runtimes weigh this against observed counts.\").default(0.5), \"success_count\": z.number().int().gte(0).describe(\"Times the lesson 'worked' when applied. Maintained by the runtime; author-supplied values are initial only.\").default(0), \"failure_count\": z.number().int().gte(0).describe(\"Times the lesson's claim was contradicted. Maintained by the runtime; author-supplied values are initial only.\").default(0), \"supersedes\": z.array(z.string().regex(new RegExp(\"^[a-z][a-z0-9-]*[a-z0-9]$\"))).describe(\"Slugs of lessons this lesson replaces. Supersession is explicit, never silent. Each cited slug MUST exist on disk.\").default([]), \"expires_at\": z.string().datetime({ offset: true }).describe(\"Soft TTL (ISO 8601). Past this instant, retrieval treats the lesson as absent by default.\").optional(), \"metadata\": z.record(z.string(), z.any()).describe(\"Vendor-specific extensions under namespaced keys (metadata.<vendor>.<field>). Standard fields MUST NOT be redefined.\").default({}) }).strict().and(z.any()).describe(\"Validates the YAML frontmatter portion of an AIP-11 LESSON.md file — one transferable lesson distilled from a completed run.\")\n\nexport type LessonFrontmatter = z.infer<typeof lessonFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { lessonFrontmatterSchema } from \"./schema.js\"\nimport type { LessonDefinition, LessonHandle } from \"./types.js\"\n\n/**\n * AIP-11 reference implementation of `defineLesson`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineLesson (AIP-11): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parseLessonManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n * Cross-field rules go in `validate(def)` after the zod check.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.slug\n *   readDescription: def.title.\n */\nexport const defineLesson = createDoctype<LessonDefinition, LessonHandle>({\n  aip: 11,\n  name: \"lesson\",\n  readIdentity: (def) => def.slug,\n  readDescription: (def) => def.title,\n  validate(def) {\n    const result = lessonFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `defineLesson (AIP-11): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-11-specific cross-field rules (if/then/allOf in\n    // the JSON Schema) — those don't translate to zod cleanly and\n    // belong here. See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    // Default build: spread the validated definition into a fresh object.\n    // Hand-tune for nested freezing (Object.freeze on arrays/objects) and\n    // for fields that need defaults applied — see @agentproto/operator\n    // for a reference shape.\n    return { ...def } as LessonHandle\n  },\n})\n"]}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { L as LessonDefinition } from './types-BTr7haEk.js';
+export { a as LessonHandle } from './types-BTr7haEk.js';
+
+/**
+ * AIP-11 reference implementation of `defineLesson`.
+ *
+ * Built on `createDoctype` so the cross-AIP invariants (id pattern,
+ * description length, top-level freeze, "defineLesson (AIP-11): …"
+ * error prefix) run uniformly with every other AIP defineX.
+ *
+ * Field-level validation runs the schema-derived zod from
+ * `./schema.ts` against the input. Same source of truth as the .md
+ * path uses (`parseLessonManifest`), so a malformed TS-authored
+ * definition fails with the same diagnostic as a malformed manifest.
+ * Cross-field rules go in `validate(def)` after the zod check.
+ *
+ * Identity / description extractors detected from the JSON Schema:
+ *   readIdentity: def.slug
+ *   readDescription: def.title.
+ */
+declare const defineLesson: (def: LessonDefinition) => Readonly<LessonDefinition>;
+
+/**
+ * @agentproto/lesson — AIP-11 LESSON.md `defineLesson` reference impl.
+ *
+ * A markdown format for storing the transferable lessons an agent extracts from successful and failed runs — title, trigger, evidence, outcome — and a contract for how runtimes distill them and inject them back into future turns.
+ *
+ * Spec: https://agentproto.sh/docs/aip-11
+ *
+ * Authoring paths:
+ *   - TS:  `defineLesson({...})` → `LessonHandle`
+ *   - MD:  `parseLessonManifest(src) → lessonFromManifest({...})` → `LessonHandle`
+ */
+declare const SPEC_NAME: "agentlesson/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { LessonDefinition, SPEC_NAME, SPEC_VERSION, defineLesson };

package/dist/index.mjs

@@ -0,0 +1,14 @@
+export { defineLesson } from './chunk-JGP7TCUI.mjs';
+
+/**
+ * @agentproto/lesson v0.1.0-alpha
+ * AIP-11 LESSON.md `defineLesson` reference implementation.
+ */
+
+// src/index.ts
+var SPEC_NAME = "agentlesson/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;AAYO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * @agentproto/lesson — AIP-11 LESSON.md `defineLesson` reference impl.\n *\n * A markdown format for storing the transferable lessons an agent extracts from successful and failed runs — title, trigger, evidence, outcome — and a contract for how runtimes distill them and inject them back into future turns.\n *\n * Spec: https://agentproto.sh/docs/aip-11\n *\n * Authoring paths:\n *   - TS:  `defineLesson({...})` → `LessonHandle`\n *   - MD:  `parseLessonManifest(src) → lessonFromManifest({...})` → `LessonHandle`\n */\n\nexport const SPEC_NAME = \"agentlesson/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { defineLesson } from \"./define-lesson.js\"\nexport type { LessonDefinition, LessonHandle } from \"./types.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { a as LessonHandle } from '../types-BTr7haEk.js';
+
+/**
+ * AIP-11 LESSON.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-11/draft/LESSON.schema.json` via
+ * json-schema-to-zod. Imported by both `define-lesson.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-lesson.ts`'s `validate(def)` instead.
+ */
+
+declare const lessonFrontmatterSchema: z.ZodIntersection<z.ZodObject<{
+    schema: z.ZodLiteral<"learning/v1">;
+    slug: z.ZodString;
+    title: z.ZodString;
+    trigger: z.ZodObject<{
+        description: z.ZodString;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        targets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            operator: z.ZodOptional<z.ZodString>;
+            role: z.ZodOptional<z.ZodString>;
+            skill: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strict>;
+    outcome: z.ZodEnum<{
+        success: "success";
+        failure: "failure";
+        mixed: "mixed";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            run: "run";
+            conversation: "conversation";
+            "work-item": "work-item";
+            audit: "audit";
+            "wiki-page": "wiki-page";
+        }>;
+        ref: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    confidence: z.ZodDefault<z.ZodNumber>;
+    success_count: z.ZodDefault<z.ZodNumber>;
+    failure_count: z.ZodDefault<z.ZodNumber>;
+    supersedes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    expires_at: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>, z.ZodAny>;
+type LessonFrontmatter = z.infer<typeof lessonFrontmatterSchema>;
+
+/**
+ * AIP-11 LESSON.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `defineLesson` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-11/draft/LESSON.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface LessonManifest {
+    frontmatter: LessonFrontmatter;
+    body: string;
+}
+declare function parseLessonManifest(source: string): LessonManifest;
+declare function lessonFromManifest(manifest: LessonManifest): LessonHandle;
+
+export { type LessonFrontmatter, type LessonManifest, lessonFromManifest, lessonFrontmatterSchema, parseLessonManifest };

package/dist/manifest/index.mjs

@@ -0,0 +1,28 @@
+import { lessonFrontmatterSchema, defineLesson } from '../chunk-JGP7TCUI.mjs';
+export { lessonFrontmatterSchema } from '../chunk-JGP7TCUI.mjs';
+import matter from 'gray-matter';
+
+/**
+ * @agentproto/lesson v0.1.0-alpha
+ * AIP-11 LESSON.md `defineLesson` reference implementation.
+ */
+function parseLessonManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseLessonManifest: missing or empty frontmatter");
+  }
+  const result = lessonFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseLessonManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function lessonFromManifest(manifest) {
+  return defineLesson(manifest.frontmatter);
+}
+
+export { lessonFromManifest, parseLessonManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/manifest/index.ts"],"names":[],"mappings":";;;;;;;;AA8BO,SAAS,oBAAoB,MAAA,EAAgC;AAClE,EAAA,MAAM,MAAA,GAAS,OAAO,MAAM,CAAA;AAC5B,EAAA,IAAI,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAE,WAAW,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,MAAM,mDAAmD,CAAA;AAAA,EACrE;AACA,EAAA,MAAM,MAAA,GAAS,uBAAA,CAAwB,SAAA,CAAU,MAAA,CAAO,IAAI,CAAA;AAC5D,EAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,gDAAA,EAA8C,OAAO,KAAA,CAAM,MAAA,CACxD,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,OAAO,OAAA,EAAQ;AAC1D;AAEO,SAAS,mBAAmB,QAAA,EAAwC;AAKzE,EAAA,OAAO,YAAA,CAAa,SAAS,WAA0C,CAAA;AACzE","file":"index.mjs","sourcesContent":["/**\n * AIP-11 LESSON.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `defineLesson` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-11/draft/LESSON.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { lessonFrontmatterSchema, type LessonFrontmatter } from \"../schema.js\"\nimport { defineLesson } from \"../define-lesson.js\"\nimport type { LessonDefinition, LessonHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/lesson/manifest\" or directly from \"@@agentproto/lesson/schema\".\nexport { lessonFrontmatterSchema, type LessonFrontmatter }\n\nexport interface LessonManifest {\n  frontmatter: LessonFrontmatter\n  body: string\n}\n\nexport function parseLessonManifest(source: string): LessonManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseLessonManifest: missing or empty frontmatter\")\n  }\n  const result = lessonFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseLessonManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function lessonFromManifest(manifest: LessonManifest): LessonHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // LessonDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return defineLesson(manifest.frontmatter as unknown as LessonDefinition)\n}\n"]}

package/dist/types-BTr7haEk.d.ts

@@ -0,0 +1,121 @@
+/**
+ * AIP-11 LessonDefinition + LessonHandle.
+ *
+ * `LessonDefinition` was generated from
+ * `resources/aip-11/draft/LESSON.schema.json` via json-schema-to-typescript.
+ * `LessonHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+/**
+ * Validates the YAML frontmatter portion of an AIP-11 LESSON.md file — one transferable lesson distilled from a completed run.
+ */
+type LessonDefinition = {
+    [k: string]: unknown;
+} & {
+    /**
+     * Spec identifier. Must be the literal string 'learning/v1'.
+     */
+    schema: "learning/v1";
+    /**
+     * Machine identifier, also the filename. Lowercase, digits, dashes. Imperative voice recommended.
+     */
+    slug: string;
+    /**
+     * One-sentence imperative title — what to do or avoid.
+     */
+    title: string;
+    trigger: {
+        /**
+         * Plain-text description of when this lesson applies.
+         */
+        description: string;
+        /**
+         * Retrieval keywords. Keep narrow; three is usually enough.
+         *
+         * @maxItems 12
+         */
+        tags?: [] | [string] | [string, string] | [string, string, string] | [string, string, string, string] | [string, string, string, string, string] | [string, string, string, string, string, string] | [string, string, string, string, string, string, string] | [string, string, string, string, string, string, string, string] | [string, string, string, string, string, string, string, string, string] | [string, string, string, string, string, string, string, string, string, string] | [string, string, string, string, string, string, string, string, string, string, string] | [string, string, string, string, string, string, string, string, string, string, string, string];
+        /**
+         * Operator / role / skill globs that scope retrieval. Empty means anyone.
+         */
+        targets?: {
+            operator?: string;
+            role?: string;
+            skill?: string;
+        }[];
+        /**
+         * Vendor-specific trigger predicates. Standard fields above MUST NOT be redefined here.
+         */
+        metadata?: {
+            [k: string]: unknown;
+        };
+    };
+    /**
+     * Whether the source run succeeded, failed, or the lesson is conditional across runs.
+     */
+    outcome: "success" | "failure" | "mixed";
+    /**
+     * Provenance — at least one evidence entry MUST resolve to a real run, conversation, work item, audit, or wiki page in the host's indices.
+     *
+     * @minItems 1
+     */
+    evidence: [
+        {
+            /**
+             * What the evidence reference points to. 'audit' = AIP-7 governance record.
+             */
+            kind: "run" | "conversation" | "work-item" | "audit" | "wiki-page";
+            /**
+             * Opaque id or path the host can resolve. Never free text.
+             */
+            ref: string;
+            /**
+             * One-line factual note about the event — not the lesson.
+             */
+            note?: string;
+        },
+        ...{
+            /**
+             * What the evidence reference points to. 'audit' = AIP-7 governance record.
+             */
+            kind: "run" | "conversation" | "work-item" | "audit" | "wiki-page";
+            /**
+             * Opaque id or path the host can resolve. Never free text.
+             */
+            ref: string;
+            /**
+             * One-line factual note about the event — not the lesson.
+             */
+            note?: string;
+        }[]
+    ];
+    /**
+     * Author's confidence in [0,1]. Default 0.5 at first sighting. Runtimes weigh this against observed counts.
+     */
+    confidence?: number;
+    /**
+     * Times the lesson 'worked' when applied. Maintained by the runtime; author-supplied values are initial only.
+     */
+    success_count?: number;
+    /**
+     * Times the lesson's claim was contradicted. Maintained by the runtime; author-supplied values are initial only.
+     */
+    failure_count?: number;
+    /**
+     * Slugs of lessons this lesson replaces. Supersession is explicit, never silent. Each cited slug MUST exist on disk.
+     */
+    supersedes?: string[];
+    /**
+     * Soft TTL (ISO 8601). Past this instant, retrieval treats the lesson as absent by default.
+     */
+    expires_at?: string;
+    /**
+     * Vendor-specific extensions under namespaced keys (metadata.<vendor>.<field>). Standard fields MUST NOT be redefined.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+};
+type LessonHandle = Readonly<LessonDefinition>;
+
+export type { LessonDefinition as L, LessonHandle as a };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@agentproto/lesson",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/lesson — AIP-11 LESSON.md reference implementation. A markdown format for storing the transferable lessons an agent extracts from successful and failed runs — title, trigger, evidence, outcome — and a contract for how runtimes distill them and inject them back into future turns.",
+  "keywords": [
+    "agentproto",
+    "aip-11",
+    "lesson",
+    "defineLesson",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-11",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/lesson"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}