@rubytech/create-realagent-code 0.1.26 → 0.1.27

package/payload/platform/plugins/loop/mcp/src/tools/viewing-search.ts

@@ -0,0 +1,92 @@
+import {
+  aggregateAcrossTeams,
+  formatAggregationResult,
+  loopGet,
+} from "../lib/loop-api.js";
+
+// ─── Loop API V2: /residential/{dept}/viewings ─────────────────
+// Fields: id, propertyId, propertyAddress, status,
+//   dateOfAppointment, dateOfAppointmentEnd,
+//   attendingAgentId, creatingAgentId, type, buyerName
+// ────────────────────────────────────────────────────────────────
+interface LoopViewingSummary {
+  id: number;
+  propertyId?: number;
+  propertyAddress?: string;
+  status?: string;
+  dateOfAppointment?: string;
+  dateOfAppointmentEnd?: string;
+  attendingAgentId?: string;
+  creatingAgentId?: string;
+  type?: string;
+  buyerName?: string;
+  [key: string]: unknown;
+}
+
+type Department = "sales" | "lettings" | "both";
+
+export async function viewingSearch(params: {
+  accountId: string;
+  department?: Department;
+  searchTerm?: string;
+  appointmentStartDate?: string;
+  appointmentEndDate?: string;
+  status?: string;
+  teamName?: string;
+  limit?: number;
+}): Promise<string> {
+  const {
+    accountId, department = "both", searchTerm,
+    appointmentStartDate, appointmentEndDate, status,
+    teamName, limit,
+  } = params;
+
+  const result = await aggregateAcrossTeams<LoopViewingSummary>(
+    accountId,
+    "viewings",
+    "loop-viewing-search",
+    async (apiKey, team) => {
+      const depts: string[] =
+        department === "both" ? ["sales", "lettings"] : [department];
+      const all: LoopViewingSummary[] = [];
+
+      for (const dept of depts) {
+        const qp: string[] = [];
+        if (searchTerm) qp.push(`SearchTerm=${encodeURIComponent(searchTerm)}`);
+        if (appointmentStartDate) qp.push(`AppointmentStartDate=${encodeURIComponent(appointmentStartDate)}`);
+        if (appointmentEndDate) qp.push(`AppointmentEndDate=${encodeURIComponent(appointmentEndDate)}`);
+        if (status) qp.push(`Status=${encodeURIComponent(status)}`);
+
+        const query = qp.length > 0 ? `?${qp.join("&")}` : "";
+        const path = `/residential/${dept}/viewings${query}`;
+        const data = await loopGet<LoopViewingSummary[]>(apiKey, path, "loop-viewing-search", team);
+        if (Array.isArray(data)) all.push(...data);
+      }
+      return all;
+    },
+    { teamName, limitPerTeam: limit ?? 50, limitTotal: limit ?? 200 }
+  );
+
+  return formatAggregationResult(
+    result,
+    (v) => {
+      const addr = v.propertyAddress ?? "Unknown property";
+      const id = v.id != null ? ` [ID: ${v.id}]` : "";
+      // dateOfAppointment is ISO datetime e.g. "2026-04-10T15:30:00"
+      const when = v.dateOfAppointment
+        ? formatDateTime(v.dateOfAppointment)
+        : "No date";
+      const viewStatus = v.status ? ` [${v.status}]` : "";
+      const buyer = v.buyerName ? ` — ${v.buyerName}` : "";
+      const viewType = v.type ? ` (${v.type})` : "";
+      return `- ${addr}${id} — ${when}${viewType}${buyer}${viewStatus}`;
+    },
+    "viewings"
+  );
+}
+
+function formatDateTime(iso: string): string {
+  const [datePart, timePart] = iso.split("T");
+  if (!timePart) return datePart;
+  return `${datePart} ${timePart.slice(0, 5)}`;
+}

package/payload/platform/plugins/loop/mcp/src/tools/viewing-update.ts

@@ -0,0 +1,53 @@
+import { loopPost, withTeamKey } from "../lib/loop-api.js";
+
+type Department = "sales" | "lettings";
+
+// Feedback parties map to swagger endpoints:
+// sales: buyer-feedback, seller-feedback
+// lettings: renter-feedback, landlord-feedback
+type FeedbackParty = "buyer" | "seller" | "renter" | "landlord";
+type Action = "note" | "feedback";
+
+// ─── Loop API V2: POST /residential/{dept}/viewings/{id}/{suffix}
+// Suffix: "note" for notes, "{party}-feedback" for feedback
+// Request body: { result: string } (StringResponse format)
+// Response: boolean success
+// ────────────────────────────────────────────────────────────────
+interface LoopBooleanResponse {
+  success?: boolean;
+  [key: string]: unknown;
+}
+
+export async function viewingUpdate(params: {
+  accountId: string;
+  teamName: string;
+  viewingId: number;
+  department: Department;
+  action: Action;
+  text: string;
+  feedbackParty?: FeedbackParty;
+}): Promise<string> {
+  const { accountId, teamName, viewingId, department, action, text, feedbackParty } = params;
+
+  if (action === "feedback" && !feedbackParty) {
+    throw new Error("feedbackParty is required when action is 'feedback'. Use: buyer, seller, renter, or landlord.");
+  }
+
+  await withTeamKey<LoopBooleanResponse>(
+    accountId,
+    teamName,
+    "viewings",
+    "loop-viewing-update",
+    async (apiKey) => {
+      const suffix = action === "note"
+        ? "note"
+        : `${feedbackParty}-feedback`;
+      const path = `/residential/${department}/viewings/${viewingId}/${suffix}`;
+      // Loop expects the text as a StringResponse body
+      return loopPost<LoopBooleanResponse>(apiKey, path, { result: text }, "loop-viewing-update", teamName);
+    }
+  );
+
+  const actionLabel = action === "note" ? "Note added" : `${feedbackParty} feedback recorded`;
+  return `${actionLabel} for viewing ${viewingId} (${department}) via team "${teamName}".`;
+}

package/payload/platform/plugins/loop/mcp/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/__tests__/**", "src/**/*.test.ts"]
+}

package/payload/platform/plugins/loop/mcp/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/__tests__/**/*.test.ts"],
+    testTimeout: 10_000,
+  },
+});

package/payload/platform/plugins/loop/skills/compliance-flag-checker/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: compliance-flag-checker
+description: "Flag AML, GDPR, DMCCA 2024 material information, ASA/CAP advertising standards, and Equality Act risks in any output before the operator approves it. Cross-cutting skill called by every workflow that produces an outbound message, a listing, terms of business, or a payment batch. Owned by the compliance specialist."
+---
+
+# Compliance flag checker
+
+A cross-cutting building-block skill. Runs against every output that touches a regulated surface (a portal listing, a terms-of-business document, an outgoing message to a buyer or vendor, a payment batch, the AML status on a deal). Returns a list of flags the operator should see before approval.
+
+## What it checks
+
+- **Material information.** DMCCA 2024 disclosure requirements for property listings: council tax band, tenure, ground rent and service charge if leasehold, property type, construction, utilities, heating, broadband, parking, and the wider Part C signals (flood risk, listed status, structural issues, planning permission, mining, and the rest). Missing items are flagged with the specific legislative requirement.
+- **Advertising standards.** ASA upheld-complaint patterns: fee transparency (VAT inclusion, mandatory surcharges disclosed), property descriptions accurate and substantiated, "local" claims supported, "leading" and "number one" claims substantiated.
+- **EPC display.** Asset rating present in any commercial media for the listing.
+- **AML state on the vendor.** Blocks a portal launch unless AML status is "passed" or the operator has explicitly overridden.
+- **GDPR.** Marketing messages to non-existing-client contacts checked for PECR opt-in basis. Data-retention prompts surfaced on close files.
+- **Equality Act.** Listing copy and outgoing messages checked for discriminatory phrasing (most commonly the "No DSS" pattern in lettings, court-declared as unlawful indirect discrimination).
+- **EAA s.21 personal interest disclosure.** Flags any output where the agent has a personal interest in the property and the disclosure has not been made.
+- **Renters' Rights Act 2025.** Where the workflow produces lettings output: bidding-ban compliance (must publish asking rent, must not request or accept above-advertised offers), discrimination ban (benefits, children), pet provisions, PRS database registration check, ombudsman membership display.
+- **Client money handling.** EAA 1979 ss.12 to 17 obligations on prescribed accounts, interest, trust requirements.
+
+## Output
+
+Each flag returns:
+
+- The cited legislation (Act, SI, regulation, code provision), with format like `[DMCCA 2024, Part 4, s.237]`
+- The specific issue
+- The remediation required
+- The penalty exposure for non-compliance
+
+The calling workflow surfaces the flags at the top of the staged output. The operator clears the flags or accepts the residual risk before approving.
+
+## What it does not do
+
+- It does not block approval. The operator decides; the skill informs.
+- It does not provide legal advice. Use "the legislation requires", "the regulatory position is", "this appears to fall short of". Never "you should" or "my advice is".
+- It does not certify a transaction or a listing as compliant. It flags gaps and cites requirements.
+- It does not amend the output it checks. Remediation is for the calling workflow or the operator.
+
+## Connectors
+
+Read: profile (compliance state, AML provider, scheme memberships), CRM (deal, vendor, listing), the deep-research tool when an unfamiliar provision needs verification.
+Write: none.
+
+## Profile keys
+
+- `realagent.compliance.cmp_scheme_membership`
+- `realagent.compliance.redress_scheme`
+- `realagent.compliance.ico_registration`
+- `realagent.compliance.mlro_designation`
+- `realagent.compliance.aml_provider`
+- `realagent.compliance.tpo_membership`
+- `realagent.compliance.propertymark_membership`

package/payload/platform/plugins/loop/skills/priority-ranker/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: priority-ranker
+description: "Order any list of items using the profile's urgency weights. Cross-cutting skill used by the morning round's top three and chase-progression's stalled list."
+---
+
+# Priority ranker
+
+A cross-cutting building-block skill. Given a list of items with feature attributes, returns the same list ordered by relative urgency.
+
+## Inputs
+
+The calling workflow passes:
+
+- A list of items. Each item has a feature attribute map (for chase-progression, the features are risk score, fee value, days stalled, recipient type, and so on).
+- An optional cap on how many top items to return (the morning round uses 3).
+
+## What it does
+
+Reads the profile's weights for the relevant features. Returns the items in descending urgency order. If the cap is supplied, returns only the top N.
+
+For the top-three case the skill also returns, alongside each item, the feature that contributed most to its rank. The calling workflow uses that feature to write the reason sentence the operator reads ("Mrs Patel, her buyer's mortgage offer expires in 9 days and the survey was booked but not done").
+
+## Learning
+
+When the operator actions a different item than the top-ranked one within the same session, the weighting reweights toward whatever feature distinguished the actioned item. Slow signal, high quality. All writes go through `profile-writer`.
+
+## What it does not do
+
+- It does not generate the reason sentence. That is `variance-narrator`.
+- It does not decide what to do with the ranked items. The calling workflow owns that.
+- It does not write to the CRM.
+
+## Connectors
+
+Read: profile (weights). No writes.
+
+## Profile keys
+
+- `realagent.priority_weights.*` (per feature, learned)
+- `realagent.priority_weights.fee_multiplier`

package/payload/platform/plugins/loop/skills/tone-matched-drafter/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: tone-matched-drafter
+description: "Draft a message in the operator's voice for a specific recipient type and channel. Cross-cutting skill used by chase-progression, new-instruction (vendor welcome), and any other workflow that needs an outgoing message. Never sends; the calling workflow owns the send gate."
+---
+
+# Tone-matched drafter
+
+The cross-cutting skill that produces every outgoing message in Real Agent. The deepest learning hook in the product: edit-before-send diffs feed back here.
+
+## Inputs
+
+The calling workflow passes:
+
+- Recipient type (vendor familiar, vendor formal, buyer familiar, buyer formal, vendor solicitor, buyer solicitor, mortgage broker, surveyor, photographer, EPC supplier, floorplan supplier, accountant, other)
+- Channel (WhatsApp, email, SMS, or "infer from recipient")
+- Intent (chase the solicitor on searches, welcome a new vendor, request a viewing, confirm a meeting, and so on)
+- Reference data (the deal record, the property record, the contact's prior messages)
+
+## What it does
+
+Reads the profile's tone preference for the recipient type and the agent's voice samples. Drafts a message that matches:
+
+- The agent's vocabulary (the words they actually use)
+- The agent's sentence length and rhythm
+- The agent's preferred greeting and sign-off for the recipient type
+- The phrases the agent has previously edited out (the pet-peeve list), which are never included
+- The channel's constraints (WhatsApp templating for first contact, email subject lines, SMS character limits)
+
+The draft is returned to the calling workflow with the channel decision attached. The workflow decides when to surface the draft to the operator and when to fire on approval.
+
+## What it does not do
+
+- It never sends. The calling workflow owns the send gate.
+- It does not negotiate. Drafts are messages the operator would send; negotiating substance is the operator's decision.
+- It does not invent facts. Every reference to a number, name, or date is read from the deal record or the connector. If a field is missing, the draft says so explicitly and the operator fills it.
+
+## Learning
+
+Every time the operator edits a draft before approval, the diff is captured and weighted into the profile's tone preference and pet-peeve list. Within a quarter, the workflow should produce drafts the agent sends without editing 80% of the time on the common recipient types.
+
+## Connectors
+
+Read: profile (tone, voice samples, pet peeves, channel preferences), CRM (deal and contact records).
+Write: none. The calling workflow handles sends.
+
+## Profile keys
+
+- `realagent.tone_profile.*` (per recipient type)
+- `realagent.voice_samples`
+- `realagent.phrasing_pet_peeves`
+- `realagent.channel_preference.<recipient_id>`
+- `realagent.tone_profile.greetings.*`
+- `realagent.tone_profile.signoffs.*`

package/payload/platform/plugins/loop/skills/variance-narrator/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: variance-narrator
+description: "Write short prose summaries of numerical changes. Used by the morning round to write the cause sentence under each stalled deal, and by month-end-close to write the two paragraphs comparing the period to the prior month and the same period last year."
+---
+
+# Variance narrator
+
+A cross-cutting building-block skill. Turns a set of numbers and structured events into a sentence or short paragraph in plain English, in the agent's voice.
+
+## Two output shapes
+
+### Cause sentence (used by morning round and chase-progression)
+
+Given a deal's state, produces one short sentence that names the most likely cause of the stall. The skill picks the pattern that fits the observable signals, not the one that sounds most dramatic. Examples:
+
+- "Mortgage offer expires in 9 days and the survey was booked but not done."
+- "Searches outstanding at day 28; solicitor last contacted day 14."
+- "Vendor unresponsive since day 12; buyer's broker has chased twice."
+
+If no pattern fits, the sentence reads "no clear cause from connectors, manual check recommended". The skill never invents a cause it cannot trace to data.
+
+### Variance paragraphs (used by month-end-close)
+
+Given the period's reconciliation totals and the two comparison periods (prior month, same month last year), produces two paragraphs in plain language with no jargon. Example:
+
+> April was GBP 8,400 down on March because three completions slipped into May, all expected to land. The reconciliation matched cleanly otherwise; the only variance was a GBP 120 referral deduction on the Norton sale.
+>
+> Year-on-year April is 15% up on the same month last year. The increase came from two completions over GBP 8,000 fee value, both new instructions taken in February.
+
+The paragraphs are suitable to paste into a board update, a tax-return cover note, or a conversation with a partner.
+
+## Voice source
+
+Reads the profile's voice samples and the operator's prior narrative paragraphs. Learns from edit-before-approve diffs.
+
+## What it does not do
+
+- It does not write outgoing messages. That is `tone-matched-drafter`.
+- It does not produce numerical totals. The calling workflow passes the numbers in; this skill writes the prose around them.
+- It does not write to the CRM or the accounting platform.
+
+## Connectors
+
+Read: profile (voice samples, narrative voice). No writes.
+
+## Profile keys
+
+- `realagent.voice_samples`
+- `realagent.close.narrative_voice_samples`
+- `realagent.cause_phrases`

package/payload/platform/plugins/loop/skills/vendor-research/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: vendor-research
+description: "Public-record and CRM-history lookup on a vendor, with the profile's privacy line enforced. Used in valuation-prep, in new-instruction AML staging, and in chase-progression when a vendor goes silent. Surfaces useful context; flags sensitive signals separately."
+---
+
+# Vendor research
+
+A cross-cutting building-block skill. Looks the vendor up across the sources the platform has access to and returns a structured summary with the privacy line applied.
+
+## What it looks at
+
+- Land Registry: ownership history, joint owners, transactions
+- The agency's CRM history with this vendor and with the property
+- Council planning portal: planning applications and decisions for the property
+- The portal record if the property has been listed before
+- Public probate registry where relevant
+- Public news sources via the deep-research tool when the brief warrants it
+
+## The privacy line
+
+The profile holds a privacy preference. Default behaviour:
+
+- **Surface.** Ownership and planning history.
+- **Flag-but-suppress.** Deaths registered against the address, ownership changes that correlate with bereavement, planning disputes, anything that the agent could not quote in the appointment without harming their reputation.
+
+The flag-but-suppress signals are not deleted; they are summarised at the top of the output as "n suppressed signals exist on this address, available on request". The operator can say "show me everything you find" to see them, or "drop the sensitive stuff" to remove the heading entirely.
+
+## Output shape
+
+A structured summary with:
+
+- How long the vendor has owned
+- Last purchase price
+- Joint owners on the title
+- Planning history (one-line per material event)
+- Prior listings (agent, asking price, sold or withdrawn)
+- CRM history with this agent
+
+Plus the suppressed-signal heading if any apply.
+
+## What it does not do
+
+- It does not draft anything to send to the vendor. That is `tone-matched-drafter`.
+- It does not produce a valuation. That is `pricing-scenario-builder`.
+- It does not write to the CRM. The calling workflow stores anything it wants kept.
+
+## Connectors
+
+Read: Land Registry, planning portal, CRM, portal data, probate registry, deep-research tool. No writes.
+
+## Profile keys
+
+- `realagent.privacy_line.surface` (list of signal types)
+- `realagent.privacy_line.suppress` (list of signal types)

package/payload/platform/plugins/teaching/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "teaching",
+  "description": "Interactive tutoring, lesson planning, and study pack generation. Teaches any subject from the knowledge base, adapting to learner age and pace. Three skills: live tutoring, parent-delivered lesson plans, and independent revision packs.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/teaching/PLUGIN.md

@@ -0,0 +1,57 @@
+---
+name: teaching
+description: "Interactive tutoring, lesson planning, and study pack generation. Teaches any subject from the knowledge base, adapting to learner age and pace. Three skills: live tutoring, parent-delivered lesson plans, and independent revision packs."
+icon: 🎓
+tools: []
+always: false
+metadata: {"platform":{"optional":true,"pluginKey":"teaching","embed":["public","admin"]}}
+---
+
+# Teaching
+
+Three skills for knowledge-based teaching and learning. Each skill draws content exclusively from the account's knowledge base — never from training data — and adapts to the learner's age (5–18).
+
+## Skills
+
+| Skill | Purpose | Audience |
+|-------|---------|----------|
+| `interactive-tutor` | Teaches a learner directly through conversation, adapting in real time | Student (via chat) |
+| `lesson-planner` | Generates self-contained lesson plans a parent or instructor can deliver | Parent / instructor |
+| `study-pack-builder` | Produces structured revision packs (flashcards, summaries, assessments) | Student (independent study) |
+
+## When to Activate
+
+The user wants to:
+- Teach a child or student a topic from the knowledge base
+- Create a lesson plan for home education or tutoring
+- Build revision materials, flashcards, or study packs from stored content
+- Prepare a student for an assessment using knowledge base content
+
+## Shared Principles
+
+- **Content from knowledge base only.** Every skill searches memory first. If the knowledge base lacks sufficient material, the skill says so — it never fills gaps from training data.
+- **Conversational context gathering.** Each skill collects requirements one question at a time, confirming before generating.
+- **Age-appropriate adaptation.** Language, examples, and complexity scale to the learner's age (5–18 years).
+- **Self-contained output.** Lesson plans, study packs, and tutoring sessions require no external resources.
+- **Domain-neutral.** The skills work for any subject present in the knowledge base — not limited to any specific curriculum, exam board, or educational system.
+
+## Tools Used
+
+No MCP server. Skills operate via existing platform tools:
+- `memory-search` — retrieve subject content from the knowledge base
+- `image_generate` — create visual aids, diagrams, and infographics
+- `render-component` — present structured choices during context gathering
+
+## References
+
+Domain knowledge files loaded on demand by each skill:
+
+| Reference | Used By | Purpose |
+|-----------|---------|---------|
+| `references/assessment.md` | interactive-tutor | Prior knowledge assessment and comprehension checking |
+| `references/classroom-conduct.md` | interactive-tutor | Standing rules for language, output format, and boundaries |
+| `references/teaching-modes.md` | interactive-tutor | Four teaching approaches (Socratic, Direct, Guided Discovery, Adaptive) |
+| `references/context-gathering.md` | lesson-planner | Student context fields and teaching mode descriptions |
+| `references/plan-structure.md` | lesson-planner | Lesson plan format, content requirements, and quality standards |
+| `references/disaggregation.md` | study-pack-builder | Building topic hierarchies from knowledge base content |
+| `references/materials.md` | study-pack-builder | Per-topic revision material generation (summaries, flashcards, assessments) |

package/payload/platform/plugins/teaching/skills/interactive-tutor/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: interactive-tutor
+description: "Teach learners interactively through conversation. Adapts to the student's age, assesses prior knowledge, teaches using four modes (Socratic, Direct, Guided Discovery, Adaptive), checks comprehension, and adjusts complexity in real time."
+---
+
+# Interactive Tutor
+
+You teach learners directly through conversation. When a student wants to learn something, you become their teacher — engaging, age-appropriate, and responsive to their understanding.
+
+## Teaching Flow
+
+```
+1. Gather basics (age, topic, lesson length, teaching mode)
+2. Assess prior knowledge (warm greeting, 1-2 questions)
+3. Teach with adaptive complexity (main loop)
+```
+
+## Step 1: Gather Basics
+
+Collect from the parent or student:
+- **Student's age**
+- **Topic** to learn
+- **Lesson length** (10-20 minutes)
+- **Teaching mode** (Socratic, Direct, Guided Discovery, or Adaptive)
+
+If the parent is present, gather from them. If the student is chatting directly, ask in age-appropriate language.
+
+## Step 2: Assess Prior Knowledge
+
+Greet the student warmly. You are now speaking DIRECTLY to the child, not the parent.
+- Brief introduction about what you'll learn together
+- 1-2 engaging questions to gauge what they already know
+- Then transition directly into teaching — don't announce a plan
+
+Load `references/assessment.md` for the full assessment approach.
+
+## Step 3: Teach
+
+Search memory for content on the topic before teaching. Teach from what the knowledge base provides — do not teach from training data.
+
+Use the selected mode. Load `references/teaching-modes.md` for mode-specific strategies.
+
+During teaching:
+- Use concrete, age-appropriate examples (toys, games, food, animals — things they know)
+- Check comprehension periodically
+- Adjust complexity based on their responses
+- Celebrate their thinking process and effort
+- Generate images with `image_generate` when a visual would help — diagrams, illustrations, worked examples. Don't narrate that you're generating; just include the image naturally in the teaching flow.
+
+Load `references/classroom-conduct.md` for conduct rules that apply at all times.
+
+## Critical Rules
+
+1. **Speak only dialogue** — no action descriptions, no asterisks, no stage directions. Only words you would say out loud.
+2. **Don't ask permission** — "Would you like me to teach you?" is wrong. Just teach.
+3. **Lead with confidence** — you are the teacher. Ask questions, guide discovery, explain concepts.
+4. **Adapt immediately** — if they struggle once, simplify. If they excel once, increase the challenge. Don't wait for patterns.
+5. **Stay on topic** — if the student goes off-topic, redirect warmly but firmly.
+6. **Content from memory only** — search the knowledge base for topic content. Do not teach from training data.

package/payload/platform/plugins/teaching/skills/interactive-tutor/references/assessment.md

@@ -0,0 +1,70 @@
+# Assessment and Comprehension
+
+## Initial Assessment (Prior Knowledge)
+
+When transitioning from gathering basics to teaching, assess what the student already knows.
+
+**You are speaking DIRECTLY to the student, not the parent.**
+
+### Opening
+1. Warm greeting: "Hello! I'm excited to teach you about [topic] today."
+2. Brief introduction: explain what you'll be learning together in simple terms
+3. Transition to assessment: "Before we dive in, I'd like to understand what you already know."
+
+### Assessment Questions
+- Ask open, engaging questions — not test questions
+- "What do you know about [topic]?" not "Can you define [topic]?"
+- "Have you ever noticed..." or "What happens when you..."
+- Keep it light — this isn't a test
+- Build on what they say with follow-up questions
+
+### Quick Assessment (1-2 Questions Max)
+1. Start with an open question about what they know
+2. Based on their answer, ask one follow-up to gauge depth
+3. Then START TEACHING immediately — don't announce a plan
+
+### Transition to Teaching
+- Wrong: "I'll now create a lesson plan for you..."
+- Right: "Let me show you something cool about [topic]..."
+- Wrong: "Would you like me to start teaching?"
+- Right: "Here's an interesting question..."
+
+## Comprehension Checks During Teaching
+
+Periodically assess whether the student understands the current concept.
+
+### How to Check
+Ask a question that tests understanding, not recall:
+- "If I changed [variable], what would happen?"
+- "Can you explain that to me in your own words?"
+- "Why do you think [concept] works that way?"
+
+### Interpreting Responses
+
+| Level | Signs | Action |
+|-------|-------|--------|
+| Full understanding | Explains concept accurately, applies it to new examples | Move on. Increase complexity. |
+| Partial understanding | Gets the idea but misses details or can't apply it | Clarify the gaps. Try a different example. |
+| Minimal understanding | Vague or partially wrong answers | Simplify. Reteach with a different approach. |
+| No understanding | Confused, silent, or completely wrong | Step back. Start from a more basic concept. |
+
+### Complexity Adjustment
+
+Track complexity on a 1-10 scale (1 = very simple, 10 = advanced).
+
+**Decrease complexity when:** Multiple wrong answers, asks for explanations, says "I don't understand", long pauses.
+
+**Increase complexity when:** Answers quickly and correctly, asks advanced questions, shows mastery, seems bored.
+
+**Maintain when:** Appropriately challenged, engaged, occasional mistakes but learning.
+
+Adjustments should be decisive (+/-2-3 levels) when the signal is clear, gradual (+/-1) when uncertain.
+
+## Mastery Tracking
+
+Throughout the session, mentally track:
+- **Concepts introduced** — what you've taught
+- **Concepts mastered** — what the student demonstrated understanding of
+- **Concepts needing work** — where they struggled
+
+Use this to guide what to focus on next. Don't move on from a concept the student hasn't grasped — reteach it differently before progressing.