@rubytech/create-maxy-code 0.1.166 → 0.1.169

package/payload/platform/plugins/teaching/skills/study-pack-builder/references/materials.md

@@ -0,0 +1,116 @@
+# Revision Materials — Per-Topic Generation
+
+For each confirmed topic, produce these outputs. All content must come from the knowledge base (memory search), not from training data.
+
+## 1. Summary
+
+A concise explanation of everything the student needs to know for this topic. Written for the student to read independently.
+
+**Behaviour:**
+- Search memory for the topic content and extract the key facts, definitions, and relationships
+- Use precise, assessment-appropriate language — not dumbed-down paraphrases
+- Organise logically: definitions first, then processes/relationships, then applications
+- Include specific details the knowledge base provides (dates, names, values, formulae, named examples)
+- Keep it dense — this is revision, not first-encounter teaching
+- Adapt the language complexity to the student's age, but do not sacrifice precision for simplicity
+
+## 2. Flashcards
+
+Question-and-answer pairs for active recall practice.
+
+**Behaviour:**
+- Write questions that mirror assessment phrasing — use command words relevant to the subject (define, explain, describe, compare, evaluate, calculate)
+- One concept per card
+- Answers should be concise and specific — what an assessor would accept
+- Cover every key term, definition, and process in the topic
+- Include application questions, not just recall — "Why does X happen?" not just "What is X?"
+- Aim for 8-15 cards per individual topic depending on content density
+
+**Format:**
+Present as a numbered list of Q/A pairs:
+```
+1. Q: [Question]
+   A: [Answer]
+```
+
+## 3. Assessment Questions
+
+Assessment-style questions at varying difficulty.
+
+**Behaviour:**
+- 3-5 questions per topic
+- Mix question types: short answer, explanation, application
+- Grade by difficulty: label each as Foundation, Intermediate, or Higher
+- Write plausible distractors for multiple-choice questions — drawn from within the same topic, not obviously absurd
+- Include the expected answer or mark scheme points for each question
+- Where the subject uses specific command words, use them
+
+## 4. Key Terms
+
+A glossary of essential vocabulary for the topic.
+
+**Behaviour:**
+- Every technical term the student would encounter in this topic
+- Definitions that match the precision expected at the student's level
+- Include the term as used in context where helpful
+- Order alphabetically within each topic
+
+## 5. Visual Overview
+
+Generate an image summarising the topic's key concepts and relationships.
+
+**Behaviour:**
+- Use `image_generate` to create a visual overview — an infographic-style image showing the main concepts, their relationships, and key facts
+- The image should work as a one-page visual reference the student can glance at during revision
+- Describe the image content precisely in the generation prompt: topic name, key concepts to include, relationships to show, any diagrams or flows that would help
+- For science topics: include diagrams (cell structures, food webs, circuit diagrams)
+- For maths topics: include worked examples and formula summaries
+- For humanities topics: include timelines, cause-and-effect flows, key figure summaries
+
+## 6. Video Summary (Future)
+
+When HeyGen video generation is available, generate a short video explanation of each topic.
+
+**Behaviour:**
+- Write a script suitable for a 2-3 minute video summary of the topic
+- The script should be structured as spoken narration — clear, direct, assessment-focused
+- Save the script to memory alongside the other materials so it can be used for video generation when the capability is available
+- Mark this output as "script ready — video generation pending"
+
+## Saving to Memory
+
+Save each topic's materials to memory as a single file at:
+```
+memory/public/study-packs/{subject}/{topic-slug}.md
+```
+
+Use a consistent structure within each file:
+```
+# {Topic Name}
+
+## Summary
+...
+
+## Flashcards
+...
+
+## Assessment Questions
+...
+
+## Key Terms
+...
+
+## Visual Overview
+[Generated image reference]
+
+## Video Script
+[Script text — pending video generation]
+```
+
+## Quality Check
+
+Before saving, verify:
+- Every flashcard and assessment answer traces back to knowledge base content
+- No content has been introduced from general knowledge or training data
+- Key terms match the terminology used in the knowledge base
+- The difficulty spread is appropriate for the student's age and level

package/payload/platform/plugins/writer-craft/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "writer-craft",
+  "description": "Manuscript review and writing craft tools grounded in neuroscience-based story theory, professional editing practice, and prose technique. 12 skills covering story architecture, reader engagement, prose craft, point of view, persuasive storytelling, editorial practice, citation style, three levels of manuscript review, and voice mirror (authorial-voice capture + application) — plus a specialist subagent for autonomous deep manuscript review.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "writer-craft": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ]
+    }
+  }
+}

package/payload/platform/plugins/writer-craft/PLUGIN.md

@@ -0,0 +1,130 @@
+---
+mcp-manifest: auto
+name: writer-craft
+description: "Manuscript review and writing craft tools grounded in neuroscience-based story theory, professional editing practice, and prose technique. 12 skills covering story architecture, reader engagement, prose craft, point of view, persuasive storytelling, editorial practice, citation style, three levels of manuscript review, and voice mirror (authorial-voice capture + application) — plus a specialist subagent for autonomous deep manuscript review."
+icon: ✍️
+tools:
+  - name: voice-tag-content
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: voice-distil-profile
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: voice-retrieve-conditioning
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: voice-record-feedback
+    publicAllowlist: false
+    adminAllowlist: true
+always: false
+embed: false
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/../premium-plugins/writer-craft/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: writer-craft
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    ADMIN_USER_ID: ${ADMIN_USER_ID}
+    SESSION_ID: ${SESSION_ID}
+    NEO4J_URI: ${NEO4J_URI}
+    NEO4J_USER: ${NEO4J_USER}
+    NEO4J_PASSWORD: ${NEO4J_PASSWORD}
+metadata: {"platform":{"optional":true,"pluginKey":"writer-craft","embed":["admin"]}}
+---
+
+# Writer Craft
+
+11 specialist skills for writers, editors, and anyone working with narrative. Each skill draws on neuroscience-based story theory (how the brain processes narrative), professional editing practice (developmental, line, and copyediting), and prose technique (sound, rhythm, word economy, POV). One specialist subagent performs autonomous deep manuscript review.
+
+## When to Activate
+
+The user is:
+- Writing fiction or nonfiction and wants craft-level guidance
+- Reviewing or editing a manuscript, chapter, scene, or passage
+- Building a story from scratch using blueprinting methodology
+- Working on persuasive writing, speeches, or advocacy storytelling
+- Formatting citations and references in Chicago author-date style
+- Seeking feedback on prose quality, POV consistency, or reader engagement
+
+## Skills
+
+### Story & Structure
+
+| Skill | Purpose |
+|-------|---------|
+| `story-architecture` | Build and analyze internal story architecture: misbelief, desire, third rail, worldview, origin scenes, scene cards |
+| `story-blueprint` | Walk a writer interactively through building a story from the inside out using the Story Genius blueprinting method |
+| `reader-engagement` | Analyze and teach reader engagement: hooking from page one, urgency, cause-and-effect, setup-payoff, conflict escalation |
+
+### Prose & Voice
+
+| Skill | Purpose |
+|-------|---------|
+| `prose-craft` | Review and teach prose technique: sound and rhythm, sentence variety, punctuation, repetition, word economy, crowding and leaping |
+| `point-of-view` | Guide point of view, narrative voice, tense, person, and indirect narration |
+| `persuasive-storytelling` | Guide persuasive storytelling for nonfiction, speeches, marketing, and advocacy |
+
+### Editing & Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `editorial-practice` | Guide professional editing methods: developmental editing, line editing, copyediting, self-editing, genre-specific considerations |
+| `citation-style` | Guide Chicago author-date citation and reference formatting per the Chicago Manual of Style (17th edition) |
+
+### Review
+
+| Skill | Purpose |
+|-------|---------|
+| `review-manuscript` | Comprehensive multi-level review covering story architecture, reader engagement, prose craft, and editorial quality |
+| `review-scene` | Deep analysis of a single scene against scene card criteria, engagement principles, and prose craft standards |
+| `review-prose` | Prose-level review analyzing sound, rhythm, sentence variety, POV consistency, word economy, and crowding/leaping balance |
+
+### Authorial Voice
+
+| Skill | Purpose |
+|-------|---------|
+| `voice-mirror` | Capture the operator's voice from their own writing (`human-only` corpus) and condition agent drafts on it. Four tools: tag historical content, distil a style card, retrieve conditioning for a drafting brief, and record operator edits as feedback. Other drafting skills (email composition, Postiz, property-brochure, prospectus) call it transparently — opt-out via `voiceMirror: false` in the calling skill's frontmatter. |
+
+## Specialist Agent
+
+| Agent | Purpose |
+|-------|---------|
+| `writer-craft--manuscript-reviewer` | Autonomous deep manuscript reviewer — reads a full manuscript or chapter and produces a structured report with inline observations and summary |
+
+The manuscript-reviewer agent operates in its own context window with file tools (Read, Glob, Grep, Write), allowing it to work through full manuscripts autonomously. Use it when the user submits a substantial piece of text for comprehensive review across all dimensions.
+
+## Tools
+
+Voice-mirror introduces four deterministic plugin tools. They route writes through `memory-write` so the graph-write gate stamps provenance on every node.
+
+| Tool | Purpose |
+|------|---------|
+| `voice-tag-content` | Stamp `authorshipMode ∈ {human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown}` on one or many `:KnowledgeDocument | :Message | :SocialPost` nodes (email threads live as `:KnowledgeDocument {source:'email'}` since Task 321). Bulk-mode for backfill batches. |
+| `voice-distil-profile` | Walk the operator's `human-only` corpus and persist a `:VoiceProfile {styleCard, generatedAt, corpusSize, feedbackEntries}` linked to the `:AdminUser`. Cadence-guarded: re-runs on ≥20% corpus growth or ≥30 days, otherwise no-op. |
+| `voice-retrieve-conditioning` | Return `{styleCard, exemplars[]}` for a drafting brief. K=5 short-form, K=15 long-form. Token-budget bounded. Graceful degradation: empty profile → `{styleCard: null, exemplars: []}`. |
+| `voice-record-feedback` | Capture an operator edit on an agent draft as a `:VoiceEdit` with a Haiku-summarised `intent`, linked back to the operator's `:VoiceProfile` via `:FEEDBACK_FOR`. |
+
+The non-voice skills continue to operate via existing platform tools (`memory-search` for knowledge retrieval). Structured choices are still presented as numbered lists in plain chat — the platform has no inline-UI component primitive on the admin / native-CC surface.
+
+## References
+
+Domain knowledge files loaded on demand by each skill. See individual skill files for their specific reference listings.
+
+| Skill | References |
+|-------|-----------|
+| `story-architecture` | `misbelief-desire-worldview.md`, `blueprinting-and-scene-cards.md`, `origin-scenes-and-escalation.md`, `inner-issue-and-protagonist-goal.md` |
+| `story-blueprint` | `blueprinting-process.md`, `blueprinting-exercises.md` |
+| `prose-craft` | `sound-and-rhythm.md`, `word-economy.md`, `punctuation-and-grammar.md`, `repetition.md` |
+| `point-of-view` | `pov-types-and-voice.md`, `tense-and-person.md`, `indirect-narration.md`, `protagonist-filter.md` |
+| `reader-engagement` | `hooking-readers.md`, `cause-effect-setup-payoff.md`, `conflict-escalation.md`, `neurochemistry-of-engagement.md` |
+| `persuasive-storytelling` | `audience-analysis.md`, `transformation-framework.md`, `crafting-persuasive-story.md`, `persuasion-case-studies.md` |
+| `editorial-practice` | `developmental-editing.md`, `line-editing.md`, `copyediting.md`, `genre-specific-editing.md`, `self-editing.md` |
+| `citation-style` | `citation-rules.md`, `reference-list-rules.md`, `journal-article-models.md`, `book-and-chapter-models.md`, `other-source-models.md` |
+| `review-manuscript` | `review-manuscript-checklist.md` |
+| `review-scene` | `scene-analysis-framework.md` |
+| `review-prose` | `prose-review-checklist.md` |
+| `voice-mirror` | No external references; the skill body defines the four tool contracts. Developer notes in `maxy-code/.docs/voice-mirror.md`. |

package/payload/platform/plugins/writer-craft/agents/writer-craft--manuscript-reviewer.md

@@ -0,0 +1,96 @@
+---
+name: manuscript-reviewer
+description: "Autonomous deep manuscript reviewer. Delegate when the user submits a manuscript, chapter, or substantial passage for comprehensive review, asks for a 'full review', 'manuscript assessment', or 'deep critique', or wants feedback across all dimensions of writing quality rather than a specific aspect."
+summary: "Reads a full manuscript or chapter and produces a structured report with inline observations and a summary covering story architecture, reader engagement, prose craft, and editorial quality."
+model: claude-sonnet-4-6
+tools: Read, Glob, Grep, Write
+---
+
+# Manuscript Reviewer Agent
+
+## Doctrine
+
+Never run uncommanded git writes. `git init`, `git commit`, `git add`, `git stash`, `git reset`, `git checkout`, and branch mutations are forbidden unless the operator named the action in this turn. If a harness precondition demands a git state you don't have, stop and report — never improvise a repo or commit.
+
+You are a manuscript reviewer with deep expertise in neuroscience-based story theory, professional editing practice, and prose craft. Your job is to read the submitted text carefully and produce a comprehensive review that helps the writer make their work better.
+
+## Your Knowledge Base
+
+You draw on three bodies of knowledge:
+
+1. **Neuroscience-based story theory** — how the brain processes narrative, why readers engage or disengage, the internal architecture of story (misbelief, desire, third rail, cause-and-effect, setup-payoff)
+2. **Professional editing practice** — developmental editing, line editing, copyediting, genre-specific considerations
+3. **Prose craft technique** — sound, rhythm, sentence variety, POV, voice, word economy, crowding and leaping
+
+## Review Process
+
+### Step 1: Read the Full Text
+Read everything before making observations. Note your first impressions — where you were engaged, confused, bored, or delighted. These are data.
+
+### Step 2: Identify the Story's Core
+Before critiquing, establish what exists:
+- What is the story about (the internal journey, not the plot)?
+- Who is the protagonist and what do they want?
+- What is the misbelief or inner issue?
+- What is the story question the reader is tracking?
+
+If these cannot be identified, that is the primary finding.
+
+### Step 3: Apply Four Lenses (in order)
+
+**Lens 1 — Story Architecture:**
+Check misbelief (specific, earned, active?), desire (in conflict with misbelief?), third rail (does every scene touch it?), cause-and-effect chain through the internal story, opening (last possible moment?), trajectory toward the Aha moment.
+
+**Lens 2 — Reader Engagement:**
+Check the opening hook, urgency, cause-and-effect scene to scene, setup-payoff integrity, conflict escalation, emotional resonance (protagonist reacting, reader able to mirror).
+
+**Lens 3 — Prose Craft:**
+Check sound and rhythm (mind's ear test), sentence variety, adjective/adverb economy, repetition (deliberate vs. accidental), POV consistency, exposition integration, crowding/leaping balance.
+
+**Lens 4 — Editorial Quality:**
+Check structural pacing, line-level clarity, internal consistency (names, timeline, details), passages where the reader would disengage.
+
+### Step 4: Produce the Report
+
+Output two parts:
+
+**Part A — Inline Observations:**
+Walk through the text, noting observations at the specific points where they occur. For each:
+- Quote or reference the passage
+- Name the issue precisely
+- Explain why it matters to the reader's experience
+- Suggest a direction for revision where possible
+
+**Part B — Summary Report:**
+
+```
+## Manuscript Review: [Title/Description]
+
+### What Works
+[Specific, genuine praise — name what the writer does well]
+
+### Story Architecture
+[Misbelief, desire, third rail, internal story, cause-and-effect]
+
+### Reader Engagement
+[Hooks, urgency, setup-payoff, conflict, emotional resonance]
+
+### Prose Craft
+[Sound, rhythm, POV, word economy, crowding/leaping]
+
+### Editorial Notes
+[Structure, pacing, consistency, line-level issues]
+
+### Priority Recommendations
+[3-5 most important things to address, ordered by impact]
+```
+
+## Review Principles
+
+- **Start with what works.** Every manuscript has strengths. Name them.
+- **Biggest issues first.** If story architecture is broken, don't lead with comma placement.
+- **Be specific.** Not "the pacing is off" but "Chapters 4-6 lose momentum because the protagonist has no active goal."
+- **Explain why.** Don't just flag problems — explain what they do to the reader.
+- **Preserve the author's voice.** Never suggest changes that would make the writing sound like you.
+- **Frame as possibilities.** "What if..." rather than "You must..."
+- **The book belongs to the author.** Help them write the best version of their book.

package/payload/platform/plugins/writer-craft/mcp/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@maxy/writer-craft-mcp",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "neo4j-driver": "^5.28.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/payload/platform/plugins/writer-craft/mcp/scripts/smoke.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Boot + shape smoke test for the writer-craft MCP server.
+ *
+ * Verifies:
+ *   1. Every compiled tool module loads without throwing.
+ *   2. Every exported handler is a function with the expected name.
+ *   3. AUTHORSHIP_MODES enum covers the five spec-required values.
+ *   4. TAGGABLE_PRIMARY_LABELS covers the four content labels.
+ *   5. `voice-retrieve-conditioning` returns the graceful-degradation
+ *      shape `{styleCard: null, exemplars: []}` when accountId is empty
+ *      (the contract the calling drafting skills depend on).
+ *
+ * Runs with no external dependencies and no neo4j connection — the
+ * graceful-degradation case never opens a session. The four other tools
+ * are not exercised against the database here; their unit test coverage
+ * is filed as a follow-up. This smoke harness catches import errors,
+ * accidental contract changes on the empty-corpus return shape, and
+ * structural drift on the exported enum.
+ *
+ * Exit code: 0 on pass, 1 on any assertion failure. Designed for CI
+ * gating and `npm run smoke` in the build pipeline.
+ */
+import { strict as assert } from "node:assert";
+
+const errors = [];
+function check(name, fn) {
+  try {
+    const result = fn();
+    if (result && typeof result.then === "function") {
+      return result.then(
+        () => console.log(`  ok   ${name}`),
+        (err) => {
+          errors.push({ name, err });
+          console.error(`  FAIL ${name}: ${err.message}`);
+        },
+      );
+    }
+    console.log(`  ok   ${name}`);
+  } catch (err) {
+    errors.push({ name, err });
+    console.error(`  FAIL ${name}: ${err.message}`);
+  }
+}
+
+console.log("[writer-craft smoke] starting");
+
+// 1. Modules load.
+const tagMod = await import("../dist/tools/voice-tag-content.js");
+const distilMod = await import("../dist/tools/voice-distil-profile.js");
+const retrieveMod = await import("../dist/tools/voice-retrieve-conditioning.js");
+const feedbackMod = await import("../dist/tools/voice-record-feedback.js");
+const corpusMod = await import("../dist/lib/voice-corpus.js");
+
+await check("voice-tag-content exports voiceTagContent function", () => {
+  assert.equal(typeof tagMod.voiceTagContent, "function");
+});
+await check("voice-tag-content exports AUTHORSHIP_MODES set of 5", () => {
+  const expected = [
+    "human-only",
+    "human-led-agent-assisted",
+    "agent-led-human-reviewed",
+    "agent-only",
+    "unknown",
+  ];
+  assert.equal(tagMod.AUTHORSHIP_MODES.size, 5);
+  for (const m of expected) assert.ok(tagMod.AUTHORSHIP_MODES.has(m), `missing ${m}`);
+});
+await check("voice-distil-profile exports voiceDistilProfile function", () => {
+  assert.equal(typeof distilMod.voiceDistilProfile, "function");
+});
+await check("voice-retrieve-conditioning exports voiceRetrieveConditioning function", () => {
+  assert.equal(typeof retrieveMod.voiceRetrieveConditioning, "function");
+});
+await check("voice-record-feedback exports voiceRecordFeedback function", () => {
+  assert.equal(typeof feedbackMod.voiceRecordFeedback, "function");
+});
+await check("VOICE_CORPUS_WHERE is non-empty string with both predicates", () => {
+  assert.equal(typeof corpusMod.VOICE_CORPUS_WHERE, "string");
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("authorshipMode IN"));
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("human-only"));
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("human-led-agent-assisted"));
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("Section"));
+});
+await check("TAGGABLE_PRIMARY_LABELS covers the four content labels", () => {
+  const labels = [...corpusMod.TAGGABLE_PRIMARY_LABELS];
+  assert.deepEqual(labels.sort(), ["Email", "KnowledgeDocument", "Message", "SocialPost"]);
+});
+
+// 2. Graceful-degradation contract — the drafting skills depend on this.
+//    Empty accountId/adminUserId path returns the empty shape without
+//    opening a neo4j session. This is the load-bearing contract.
+await check(
+  "voice-retrieve-conditioning returns empty shape on missing accountId",
+  async () => {
+    const result = await retrieveMod.voiceRetrieveConditioning({
+      accountId: "",
+      adminUserId: "u",
+      brief: { format: "short" },
+    });
+    assert.deepEqual(result, { styleCard: null, exemplars: [] });
+  },
+);
+await check(
+  "voice-retrieve-conditioning returns empty shape on missing adminUserId",
+  async () => {
+    const result = await retrieveMod.voiceRetrieveConditioning({
+      accountId: "acc",
+      adminUserId: "",
+      brief: { format: "long" },
+    });
+    assert.deepEqual(result, { styleCard: null, exemplars: [] });
+  },
+);
+
+// 3. voice-tag-content validates the mode enum before any DB work.
+await check("voice-tag-content rejects an invalid mode", async () => {
+  await assert.rejects(
+    () =>
+      tagMod.voiceTagContent({
+        nodeIds: ["x"],
+        mode: "not-a-mode",
+        accountId: "acc",
+      }),
+    /invalid authorshipMode/,
+  );
+});
+await check("voice-tag-content rejects empty accountId", async () => {
+  await assert.rejects(
+    () =>
+      tagMod.voiceTagContent({
+        nodeIds: ["x"],
+        mode: "human-only",
+        accountId: "",
+      }),
+    /accountId is required/,
+  );
+});
+await check("voice-tag-content returns zero counts on empty nodeIds (no DB hit)", async () => {
+  const result = await tagMod.voiceTagContent({
+    nodeIds: [],
+    mode: "human-only",
+    accountId: "acc",
+  });
+  assert.deepEqual(result, { updated: 0, skipped: 0, skippedReasons: {} });
+});
+
+if (errors.length > 0) {
+  console.error(`\n[writer-craft smoke] FAILED — ${errors.length} assertion(s)`);
+  process.exit(1);
+}
+console.log("\n[writer-craft smoke] all passed");