pi-gnosis 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.0
+
+- Rebuilt package around Circuitry as the executable agentic programming layer.
+- Removed the incorrect generic simulation-node framing. Circuitry graphs themselves are the multi-agent workflow programs.
+- Added frozen graph programs for research, tutoring, note export, Manim lecture generation, cleanup, and smoke testing.
+- Added required dependency on `pi-web-access` and optional dependency on `pi-exa-search` for graph agents that need web tools.
+- Centralized runtime/model configuration in `config/gnosis.config.json`; all graph runtimes and agent nodes use `model: inherit`.
+- Added bundled `manim-video` skill with credit to Nous/Hermes documentation.
+- Added explicit DAG-state vs Obsidian storage contract.
+- Added safe cleanup graph and cleanup policy.
+- Added tests that validate graph shape, safe cleanup planning, probe policy, review scheduling, and Manim project generation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 darkhorseprojects
+
+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/NOTICE

@@ -0,0 +1,7 @@
+Pi-GNOSIS NOTICE
+
+This package depends on DarkHorseProjects pi-circuitry and the transitive Circuitry runtime/spec.
+
+The bundled Manim skill is an original local skill inspired by Nous Research / Hermes Agent's public "Manim Video" skill documentation. It is not an official Hermes skill release, and this package does not depend on Hermes Agent. Credit: Nous Research / Hermes Agent documentation, "Manim Video - Manim CE animations: 3Blue1Brown math/algo videos".
+
+The research framework references public academic work on automated literature review generation, agentic RAG, intelligent tutoring systems, knowledge tracing, retrieval practice, and automated short-answer grading. See framework/research-foundations.md.

package/README.md

@@ -0,0 +1,56 @@
+# pi-gnosis
+
+[![CI](https://github.com/darkhorseprojects/pi-gnosis/actions/workflows/ci.yml/badge.svg)](https://github.com/darkhorseprojects/pi-gnosis/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Source-grounded research and non-linear tutoring for [Pi](https://github.com/earendil-works/pi-coding-agent). pi-gnosis turns learning requests into executable Circuitry graph programs instead of lengthy prose responses.
+
+```text
+normal Pi conversation
+  -> Pi decides pi-gnosis is useful
+  -> Pi runs one or more graphs through pi-circuitry
+  -> graph agents use pi-web-access for research
+  -> results become DAG state, Obsidian notes, or Manim lecture projects
+```
+
+## Features
+
+- **Non-linear tutoring**: Adaptive learning that responds to demonstrated understanding
+- **Source-grounded research**: Every claim traces back to fetched sources
+- **Open-ended probes**: Recall, explain, transfer, contrast, debug - no multiple-choice
+- **Obsidian integration**: Export notes to a compatible learning vault
+- **Manim lectures**: Generate video lectures with local Manim CE
+- **Knowledge tracing**: DAG state tracks understanding depth over time
+
+## Graph Programs
+
+| Graph | Purpose |
+| --- | --- |
+| `graphs/research.circuitry.yaml` | Delegated research pipeline: scope, query planning, source discovery, fetching, claim extraction, critique, KT DAG seed |
+| `graphs/tutoring-session.circuitry.yaml` | Non-linear tutoring turn planner with open-ended probes and state updates |
+| `graphs/note-export.circuitry.yaml` | Obsidian-compatible note export from canonical DAG state |
+| `graphs/manim-lecture.circuitry.yaml` | Video/lecture project generation using bundled manim-video skill |
+| `graphs/cleanup.circuitry.yaml` | Safe cleanup pass for temporary artifacts created by graph runs |
+| `graphs/minimal-smoke.circuitry.yaml` | Tiny graph for Circuitry shape validation |
+
+## Installation
+
+```bash
+npm install
+npm test
+```
+
+The package pins `@darkhorseprojects/pi-circuitry` exactly and validates generated Circuitry YAML against the bundled v0.2 structural checker. Runtime execution requires a Pi environment with network access.
+
+## Dependencies
+
+Required:
+- `@darkhorseprojects/pi-circuitry` v0.2.6
+- `pi-web-access` ^0.10.7
+
+Optional:
+- `pi-exa-search` for Exa-first source discovery
+
+## License
+
+MIT - see [LICENSE](LICENSE) file for details.

package/bin/pi-gnosis.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildManimProject, buildReviewSchedule, getGraphProgram, listGraphPrograms, loadConfig, planCleanup, storagePlan, validateCircuitryFile } from '../src/index.js';
+
+function arg(name, fallback = undefined) {
+  const prefix = `--${name}=`;
+  const found = process.argv.find((a) => a.startsWith(prefix));
+  if (found) return found.slice(prefix.length);
+  const idx = process.argv.indexOf(`--${name}`);
+  if (idx >= 0) return process.argv[idx + 1];
+  return fallback;
+}
+
+function usage() {
+  console.log(`pi-gnosis commands:\n  graphs\n  graph <name>\n  validate <file...>\n  storage-plan --topic <topic>\n  schedule <concept-scores.json> [--today YYYY-MM-DD]\n  manim-sample --topic <topic> --out <dir>\n  cleanup-plan <path...> [--apply] [--allow-media]`);
+}
+
+const cmd = process.argv[2];
+try {
+  if (!cmd || cmd === 'help' || cmd === '--help') {
+    usage();
+  } else if (cmd === 'graphs') {
+    console.log(JSON.stringify(listGraphPrograms(), null, 2));
+  } else if (cmd === 'graph') {
+    const name = process.argv[3] || 'research';
+    console.log(getGraphProgram(name));
+  } else if (cmd === 'validate') {
+    const files = process.argv.slice(3);
+    if (files.length === 0) throw new Error('validate requires at least one file');
+    const results = files.map((f) => validateCircuitryFile(f));
+    const issues = results.flatMap((r) => r.issues);
+    if (issues.length) throw new Error(issues.join('\n'));
+    console.log(JSON.stringify({ ok: true, files }, null, 2));
+  } else if (cmd === 'storage-plan') {
+    console.log(JSON.stringify(storagePlan({ topic: arg('topic', 'topic') }), null, 2));
+  } else if (cmd === 'schedule') {
+    const file = process.argv[3];
+    if (!file) throw new Error('schedule requires a JSON file');
+    const concepts = JSON.parse(await import('node:fs').then((fs) => fs.readFileSync(file, 'utf8')));
+    console.log(JSON.stringify(buildReviewSchedule(concepts, { today: arg('today') }), null, 2));
+  } else if (cmd === 'manim-sample') {
+    const topic = arg('topic', 'knowledge tracing DAGs');
+    const out = arg('out', '/tmp/pi-gnosis-manim-sample');
+    const project = buildManimProject({ topic, outputRoot: out, write: true });
+    console.log(JSON.stringify({ ok: true, projectRoot: project.projectRoot, files: Object.keys(project.files) }, null, 2));
+  } else if (cmd === 'cleanup-plan') {
+    const paths = process.argv.slice(3).filter((x) => !x.startsWith('--'));
+    console.log(JSON.stringify(planCleanup(paths, { applyCleanup: process.argv.includes('--apply'), allowGeneratedMediaCleanup: process.argv.includes('--allow-media') }), null, 2));
+  } else if (cmd === 'config') {
+    console.log(JSON.stringify(loadConfig(), null, 2));
+  } else {
+    throw new Error(`Unknown command: ${cmd}`);
+  }
+} catch (err) {
+  console.error(err.message);
+  process.exitCode = 1;
+}

package/config/gnosis.config.json

@@ -0,0 +1,51 @@
+{
+  "schema": "pi-gnosis.config.v1",
+  "runtime": {
+    "provider": "pi",
+    "model": "inherit"
+  },
+  "circuitry": {
+    "version": "0.2",
+    "modelPolicy": "Every graph and every agent node uses model: inherit unless a user explicitly overrides it in Pi."
+  },
+  "paths": {
+    "dagStateRoot": ".pi-gnosis/state",
+    "temporaryRoot": ".pi-gnosis/tmp",
+    "obsidianRoot": "notes",
+    "manimRoot": "manim"
+  },
+  "webTools": {
+    "required": [
+      "web_search",
+      "fetch_content"
+    ],
+    "optional": [
+      "exa_search"
+    ],
+    "source": "pi-web-access is required; pi-exa-search is optional and preferred for first-pass source discovery when installed."
+  },
+  "policies": {
+    "probing": {
+      "multipleChoice": "forbidden",
+      "preferred": [
+        "recall",
+        "explain",
+        "transfer",
+        "contrast",
+        "debug",
+        "teach_back",
+        "source_check"
+      ]
+    },
+    "writes": {
+      "default": "manifest-first",
+      "safeRoots": [
+        ".pi-gnosis/state",
+        ".pi-gnosis/tmp",
+        "notes",
+        "manim"
+      ],
+      "deletePolicy": "cleanup graph may delete only temporary files under .pi-gnosis/tmp unless the user explicitly authorizes deleting generated media."
+    }
+  }
+}

package/framework/circuitry-first.md

@@ -0,0 +1,18 @@
+# Circuitry-first architecture
+
+Pi-GNOSIS treats Circuitry as the executable programming language for intelligent work.
+
+Do not compress the workflow into one giant Pi prompt. Use top-level Pi skill instructions only to decide when and how to launch the frozen graph programs. The graphs do the delegation.
+
+## Design rules
+
+1. A graph is the multi-agent workflow. Do not add a single generic "simulation" node.
+2. Each agent must have isolated responsibility, explicit inputs, whitelisted tools, whitelisted skills, and an `expect` schema.
+3. Research, note export, video generation, tutoring turns, and cleanup are separate graph programs because they have different side-effect and tool policies.
+4. Use `runtime.provider: pi` and `model: inherit` so pi-circuitry inherits the active Pi conversation model.
+5. Prefer source-ledger and claim-ledger artifacts over prose summaries.
+6. Read/write agents must operate under manifest-first constraints and safe roots.
+
+## Why this is better than text instructions
+
+Text instructions make one top-level agent remember every concern at once. Circuitry lets Pi run delegated programs with explicit context boundaries: one agent plans queries, another curates sources, another extracts claims, another builds a KT DAG, another writes notes, another creates a Manim project, and a final agent audits results.

package/framework/cleanup-policy.md

@@ -0,0 +1,22 @@
+# Cleanup policy
+
+Cleanup is a graph program, not an ad hoc shell habit.
+
+The cleanup graph may identify:
+
+- temporary graph-run files under `.pi-gnosis/tmp/`;
+- failed draft Manim renders under `manim/**/media/`;
+- scratch files declared in `output_manifest.json` as temporary;
+- stale intermediate prompts or extracted snippets that were superseded by ledgers.
+
+It must preserve:
+
+- `.pi-gnosis/state/**` ledgers;
+- final notes;
+- final videos;
+- source ledgers;
+- claim ledgers;
+- user-authored files;
+- scripts and configs.
+
+Default behavior is plan-only. Destructive cleanup requires either `apply_cleanup: true` in the cleanup request or explicit user confirmation, and even then deletion is restricted to safe temporary roots.

package/framework/obsidian-contract.md

@@ -0,0 +1,31 @@
+# Obsidian note contract
+
+Obsidian export is optional, but this package assumes many Pi users will actually use it.
+
+Each topic export should contain:
+
+```text
+00-map.md
+source-ledger.md
+concepts/<concept>.md
+misconceptions.md
+probes.md
+review-plan.md
+reflection-log.md
+manifest.md
+```
+
+Concept notes should include:
+
+- plain-language definition;
+- why it matters;
+- prerequisites;
+- contrasts;
+- examples;
+- common wrong variants;
+- source support ids;
+- open-ended retrieval prompts;
+- transfer prompts;
+- links to related notes.
+
+Obsidian files are learner memory. Do not treat them as the canonical source ledger unless the DAG state has imported and validated them.

package/framework/probing-policy.md

@@ -0,0 +1,20 @@
+# Probing policy
+
+Pi-GNOSIS does not use multiple-choice questions for diagnostic probing.
+
+Allowed probe types:
+
+- recall from memory;
+- explain in the learner's own words;
+- generate a new example;
+- solve or complete a worked example;
+- transfer to a new case;
+- contrast two concepts;
+- debug a flawed explanation;
+- predict-observe-explain;
+- teach-back;
+- source check.
+
+Why: recognition-only formats can hide shallow familiarity. Open-ended probes make the learner externalize reasoning, reveal misconceptions, and produce evidence that can update the KT DAG.
+
+Answer keys and rubrics may exist, but they should be hidden below the prompt or kept in the DAG state until after the learner attempts the probe.

package/framework/research-foundations.md

@@ -0,0 +1,46 @@
+# Research foundations used by Pi-GNOSIS
+
+This file is a design grounding memo, not a frozen bibliography.
+
+## Automated research pipelines
+
+Automated research/survey systems work better when they decompose the job. Agentic AutoSurvey uses specialized agents for paper search, topic mining/clustering, survey writing, and quality evaluation, reporting higher synthesis quality than a single baseline survey generator. Design implication: Pi-GNOSIS uses separate Circuitry agents for scope, source discovery, extraction, synthesis, critique, and learner artifact routing.
+
+Citation integrity remains a hard failure mode. Generated reviews can look polished while missing disagreement, hallucinating references, or failing to connect claims to sources. Design implication: every non-obvious claim should map to source ids, and quality gates should reject unsupported synthesis.
+
+## Agentic RAG
+
+Agentic RAG and multi-agent RAG research motivate decomposing retrieval-heavy tasks into planning, source discovery, extraction, and synthesis agents. Multi-agent RAG work such as MA-RAG uses planner/extractor/QA-style roles to handle ambiguous, multi-hop information seeking. Design implication: the research graph is a Circuitry program with role-specific agents and whitelisted web tools, not a single web-search prompt.
+
+## Intelligent tutoring and KT
+
+Intelligent tutoring systems traditionally maintain a learner model and use interactions to update the estimate of what the learner understands. Knowledge tracing estimates learner knowledge from interactions, but modern reviews warn that high predictive accuracy and interpretability do not always coexist. Design implication: Pi-GNOSIS stores transparent evidence records in the KT DAG instead of opaque mastery labels.
+
+LLM tutoring papers warn that being good at solving problems is not the same as being good at tutoring. Design implication: Pi-GNOSIS separates subject research, learner-state modeling, probing, feedback, and next-turn planning.
+
+## Open-ended probing
+
+Open-ended questions reveal reasoning better than recognition-only formats. LLM-based short-answer grading work suggests open-ended formative assessment is increasingly practical, although not perfect. Design implication: Pi-GNOSIS forbids multiple-choice diagnostic probes and instead uses recall, explain, transfer, contrast, debug, teach-back, and source-check prompts.
+
+## Retrieval practice and spacing
+
+Retrieval practice and spaced review are more durable than passive rereading for many learning tasks. More effortful retrieval often produces better long-term memory than easy recognition. Design implication: Pi-GNOSIS produces review schedules and open-ended retrieval prompts for concepts with high decay or misconception risk.
+
+## Memetics, cautiously
+
+Memetics is used only as a constrained lens for concept variants, transmission pathways, attractive wrong explanations, and misconception risk. It is not treated as a literal idea-virus science and never replaces source evidence.
+
+## Sources to refresh during research runs
+
+- Circuitry spec: https://github.com/darkhorseprojects/circuitry/blob/main/docs/SPEC.md
+- Circuitry README: https://github.com/darkhorseprojects/circuitry
+- pi-web-access: https://github.com/nicobailon/pi-web-access
+- pi-exa-search: https://github.com/najibninaba/pi-exa-search
+- Hermes Manim Video docs: https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/creative/creative-manim-video
+- Agentic AutoSurvey: https://arxiv.org/abs/2509.18661
+- MathTutorBench: https://arxiv.org/abs/2502.18940
+- Beyond Final Answers: https://arxiv.org/abs/2503.16460
+- Systematic Review of KT and LLMs in Education: https://arxiv.org/abs/2412.09248
+- Can LLMs Grade Short-Answer Reading Comprehension Questions: https://arxiv.org/abs/2310.18373
+- MA-RAG: https://arxiv.org/abs/2505.20096
+- RAG-Reasoning Survey: https://arxiv.org/abs/2507.09477

package/framework/storage-contract.md

@@ -0,0 +1,36 @@
+# Storage contract: DAG state vs Obsidian
+
+## Canonical DAG state
+
+DAG state is machine-readable and lives under `.pi-gnosis/state/<run-id>/`. It is what Pi-GNOSIS uses to resume and route learning.
+
+Store here:
+
+- `run_manifest.json`: run id, topic, graph, package version, timestamps, config snapshot.
+- `source_ledger.json`: source ids, urls, dates, source type, reliability notes, claims supported.
+- `claim_ledger.json`: atomic claims, support, conflicts, uncertainty, source ids.
+- `kt_dag.json`: concepts, prerequisites, relation types, evidence records, review risks.
+- `learner_state.json`: observed evidence, probe outcomes, confidence, misconception markers.
+- `review_schedule.json`: next review dates and reasons.
+- `output_manifest.json`: files intentionally written by graph agents.
+
+## Obsidian notes
+
+Obsidian is optional but first-class for the learner. It is the human-facing memory surface.
+
+Store here:
+
+- concept notes written for reading and review;
+- source-ledger summaries with links;
+- reflection logs;
+- open-ended probes and answer rubrics;
+- review plans;
+- the learner's own explanations and corrections.
+
+Pi can read Obsidian to infer what the learner has already explained, but it must treat notes as learner evidence rather than authoritative source truth.
+
+## Rule
+
+DAG state answers: what does the system know, why, with what evidence, and what should run next?
+
+Obsidian answers: what can the person read, edit, connect, and study?

package/framework/why-kt-dag.md

@@ -0,0 +1,18 @@
+# Why Pi-GNOSIS keeps a KT DAG
+
+A normal conversation transcript is not enough to decide what the learner knows. Obsidian notes are also not enough: they show what was written, not whether prerequisite concepts are stable, decaying, or confused.
+
+Pi-GNOSIS keeps a knowledge-tracing DAG because the user can stop, resume, jump topics, ask for video, revise notes, or reveal a misconception at any point. The graph stores:
+
+- concepts;
+- prerequisite and contrast links;
+- source support;
+- learner evidence;
+- misconception risk;
+- decay risk;
+- next open-ended probe targets;
+- review intervals.
+
+It is not a rigid linear curriculum. It is a resumable state graph for non-linear tutoring.
+
+The package borrows from knowledge tracing in intelligent tutoring systems: learner state is updated from observed interactions. It deliberately avoids classic binary mastered/not-mastered overconfidence. State updates must cite evidence: an open-ended explanation, worked example, transfer attempt, source check, or learner note.

package/graphs/README.md

@@ -0,0 +1,15 @@
+# Pi-GNOSIS Circuitry graphs
+
+These graphs are frozen programs for pi-circuitry. Do not treat them as examples only. Pi should run them when the skill routes work here.
+
+Every graph uses:
+
+```yaml
+runtime:
+  provider: pi
+  model: inherit
+```
+
+Every agent node also uses `model: inherit`.
+
+The graph itself is the multi-actor workflow. Do not add a single generic simulation node.

package/graphs/cleanup.circuitry.yaml

@@ -0,0 +1,94 @@
+circuitry: "0.2"
+title: "Pi-GNOSIS Cleanup Program"
+description: |
+  Frozen Circuitry program for planning and, when explicitly allowed, applying safe cleanup of non-permanent artifacts created by Pi-GNOSIS graph runs.
+runtime:
+  provider: pi
+  model: inherit
+validation:
+  rules:
+    - no-self-loops
+    - no-unknown-edge-endpoints
+    - no-cycles
+    - rule: require-executable-inputs
+      executableKinds: [agent, tool]
+resources:
+  cleanup_request:
+    type: text
+    label: "Cleanup request"
+    value: |
+      run_id: ""
+      dag_state_path: ".pi-gnosis/state"
+      temp_path: ".pi-gnosis/tmp"
+      manim_root: "manim"
+      apply_cleanup: false
+      allow_generated_media_cleanup: false
+  cleanup_policy:
+    type: text
+    label: "Cleanup policy"
+    value: |
+      Default is plan-only. Safe deletion is restricted to temporary files under .pi-gnosis/tmp. Generated Manim media may be proposed for cleanup, but only deleted if allow_generated_media_cleanup is true. Never delete DAG state, source ledgers, claim ledgers, notes, final videos, scripts, configs, or user-authored files.
+  artifact_census:
+    type: agent
+    identity: "Artifact Census Agent"
+    model: inherit
+    inputs: [cleanup_request, cleanup_policy]
+    skills: [pi-gnosis]
+    tools: [read_file, grep, shell]
+    expect:
+      discovered_artifacts:
+        type: list
+        items:
+          path: str
+          category: str
+          source: str
+      protected_artifacts:
+        type: list
+        items: str
+      uncertainty:
+        type: list
+        items: str
+    instructions: |
+      Inspect manifests and safe roots if tools are available. Do not delete. Classify temporary, generated-media, final-output, state, note, source, config, or unknown. Unknown is protected. Output only valid JSON matching expect.
+  cleanup_decider:
+    type: agent
+    identity: "Cleanup Decision Agent"
+    model: inherit
+    inputs: [artifact_census, cleanup_policy, cleanup_request]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      deletion_plan:
+        type: list
+        items:
+          path: str
+          reason: str
+          allowed_now: bool
+      keep_plan:
+        type: list
+        items:
+          path: str
+          reason: str
+      needs_user_confirmation:
+        type: list
+        items: str
+    instructions: |
+      Decide what can be deleted. Only temporary files under .pi-gnosis/tmp are allowed when apply_cleanup is true. Media cache cleanup needs allow_generated_media_cleanup. Everything else is keep/protected. Output only valid JSON matching expect.
+  cleanup_executor:
+    type: agent
+    identity: "Safe Cleanup Executor"
+    model: inherit
+    inputs: [cleanup_decider, cleanup_policy, cleanup_request]
+    skills: [pi-gnosis]
+    tools: [shell]
+    expect:
+      status: str
+      deleted:
+        type: list
+        items: str
+      not_deleted:
+        type: list
+        items: str
+      audit_log: str
+    instructions: |
+      If apply_cleanup is false, do not delete anything; return plan-only status. If true, delete only paths that cleanup_decider marked allowed_now and that are inside safe temporary roots. Use conservative commands. Never use recursive deletion outside safe roots. Output only valid JSON matching expect.

package/graphs/manim-lecture.circuitry.yaml

@@ -0,0 +1,137 @@
+circuitry: "0.2"
+title: "Pi-GNOSIS Manim Lecture Program"
+description: |
+  Frozen Circuitry program for generating a Manim CE lecture project from researched/KT state. The Manim-producing agent directly loads the bundled manim-video skill.
+runtime:
+  provider: pi
+  model: inherit
+validation:
+  rules:
+    - no-self-loops
+    - no-unknown-edge-endpoints
+    - no-cycles
+    - rule: require-executable-inputs
+      executableKinds: [agent, tool]
+resources:
+  lecture_request:
+    type: text
+    label: "Lecture request"
+    value: |
+      topic: ""
+      dag_state_path: ".pi-gnosis/state"
+      output_root: "manim"
+      render: "draft-if-environment-ready"
+      apply_writes: false
+  manim_policy:
+    type: text
+    label: "Manim side-effect policy"
+    value: |
+      Use the bundled manim-video skill. Write only inside output_root. Produce plan.md, scene_spec.json, script.py, render.sh, and README.md. Do not delete anything. Mark media/ as cleanup-eligible only after final outputs are preserved.
+  visual_learning_policy:
+    type: text
+    label: "Visual learning policy"
+    value: |
+      A lecture should have one narrative arc, one misconception or bottleneck to fix, and a small number of scenes. Prefer visual structure over text dumps. The aha moment should be visible.
+  lecture_state_importer:
+    type: agent
+    identity: "Lecture State Importer"
+    model: inherit
+    inputs: [lecture_request, visual_learning_policy]
+    skills: [pi-gnosis]
+    tools: [read_file, grep]
+    expect:
+      usable_concepts:
+        type: list
+        items: str
+      source_ids_to_carry:
+        type: list
+        items: str
+      learner_bottlenecks:
+        type: list
+        items: str
+      missing_state:
+        type: list
+        items: str
+    instructions: |
+      Read DAG state when available. Extract concepts, misconceptions, source ids, and learner bottlenecks relevant to the requested lecture. Do not write. Output only valid JSON matching expect.
+  lecture_storyboarder:
+    type: agent
+    identity: "Manim Lecture Storyboarder"
+    model: inherit
+    inputs: [lecture_state_importer, visual_learning_policy]
+    skills: [pi-gnosis, manim-video]
+    tools: []
+    expect:
+      narrative_arc: str
+      scenes:
+        type: list
+        items:
+          name: str
+          learning_goal: str
+          visual_metaphor: str
+          key_animation: str
+          narration_beat: str
+      aha_moment: str
+      what_to_avoid:
+        type: list
+        items: str
+    instructions: |
+      Design the lecture as a Manim visual explanation. Use source ids when claims depend on research. Keep scenes compact. Output only valid JSON matching expect.
+  manim_project_builder:
+    type: agent
+    identity: "Manim Project Builder"
+    model: inherit
+    inputs: [lecture_request, manim_policy, lecture_storyboarder]
+    skills: [pi-gnosis, manim-video]
+    tools: [read_file, write_file, edit_file]
+    expect:
+      project_root: str
+      files_written_or_planned:
+        type: list
+        items: str
+      render_command: str
+      cleanup_candidates:
+        type: list
+        items: str
+    instructions: |
+      If apply_writes is false, return file contents as planned artifacts. If writes are enabled by Pi, write only under output_root. Create plan.md, scene_spec.json, script.py, render.sh, and README.md. Do not render here. Output only valid JSON matching expect.
+  render_preflight:
+    type: agent
+    identity: "Manim Render Preflight"
+    model: inherit
+    inputs: [manim_project_builder, manim_policy]
+    skills: [manim-video]
+    tools: [read_file, shell]
+    expect:
+      can_render: bool
+      checks:
+        type: list
+        items:
+          name: str
+          status: str
+          detail: str
+      draft_render_command: str
+      if_not_rendered: str
+    instructions: |
+      Check Python syntax, Manim availability, ffmpeg availability, and LaTeX only if MathTex is used. If the environment is not ready, do not pretend a video was rendered. Output only valid JSON matching expect.
+  visual_quality_gate:
+    type: agent
+    identity: "Manim Visual Quality Gate"
+    model: inherit
+    inputs: [lecture_storyboarder, manim_project_builder, render_preflight, visual_learning_policy]
+    skills: [pi-gnosis, manim-video]
+    tools: [read_file]
+    expect:
+      status: str
+      learning_objective_match: str
+      clutter_risks:
+        type: list
+        items: str
+      source_claim_risks:
+        type: list
+        items: str
+      cleanup_manifest:
+        type: list
+        items: str
+    instructions: |
+      Review the planned or written Manim project. Flag visual clutter, missing aha moment, overuse of text, unsupported research claims, and cleanup candidates. Output only valid JSON matching expect.