Calmer Homework Time with HexClaw AI: Engineering the First K12 Flagship Scenario

Can a general-purpose agent platform support a genuinely trustworthy specialist scenario without contaminating its core or disturbing other users? The familiar “general or vertical?” question returns in the agent era. For this version, HexClaw chose a scenario where mistakes matter especially deeply : helping children with homework. One AI mistake becomes a parent's mistaken explanation and a child's mistaken understanding .

The everyday version is a familiar Chinese joke: parent and child get along until homework begins. Behind it is a public frustration that official media have covered for five years: China Youth Daily asked how parents could escape “homework tutoring anxiety” in 2021, and Zhejiang Publicity was still asking why homework tutoring drives parents to anger in February 2026. In our view, no product has fully met that need in those five years.

Headlines have certainly noticed. Search for AI homework help and the same formula appears: “From homework chaos to family harmony—all it takes is AI” . It contains some truth: today's multimodal models recognize photographed questions and answer them. Leading vendors are also moving toward guided learning: Anthropic's Claude for Education Learning mode, OpenAI's ChatGPT Study mode, and Google's Gemini Guided Learning launched in 2025 for different stages from higher education to K12. But articles using that formula usually test whether the AI explains smoothly, rarely treating a wrong explanation as an engineering problem. Put plainly: would you teach your own child using the AI's answer? The closer a parent is to exhaustion, the less capacity they have to verify every step.

Parents also need more than a correct answer. The explanation must use what the child has learned, without baffling a fifth grader with simultaneous linear equations. Sensitive family data—mistakes and learning records—must not drift into the cloud without a clear account.

HexClaw AI Desktop v0.5.0-beta.3 (backend hexclaw v0.5.0-beta.1) makes homework tutoring the platform's first flagship scenario: a K12 lesson-preparation assistant for parents . Parents prepare teacher-like explanations rather than placing a child directly in front of AI. With the default local deployment, learning assets stay on the local machine. This version covers primary grades 1–6; middle and high school remain long-term plans. The Chinese title changes “filial obedience” to “smiles”: a smiling child matters more. This article examines what really lies between AI and a calmer homework routine: first, why the AI can teach—evidence-based Skills grounded in educational theory, plus a two-layer design putting correctness in Go and explanation in Markdown—then three questions about trust that are entirely engineering questions .

The central judgment
Putting AI into tutoring is difficult for more than explaining a problem; large models can already do that. The challenge is three questions of trust :
① What if the explanation is wrong? —a calculation-evidence chain records program-execution evidence separately from model judgment;
② Where is the data stored? —storage follows the local or cloud service, while cloud-model use is checked by purpose and data category;
③ Will the scenario erode the platform? —K12 is a scenario package removable at compile time; the platform must still work independently after removal.

The 30-second version :
Desktop v0.5.0-beta.3 makes tutoring HexClaw's first scenario package. A photo's source is saved before per-question recognition. Blank questions give parents answers and explanations; completed questions are judged separately. Precisely evaluable problems use deterministic code in the current service; reliable question assets can reuse verified solutions; the rest use Solver + Verifier. For computational verification, the app executes model-generated code, with separate evidence for the final value, the process, and the parent explanation . Mistakes follow a 1 / 3 / 7 / 14-day review ladder, and learning profiles can be exported. Durable tasks and itemized delivery receipts connect “computed” to “received by the parent.” Six backend seams, Manifest v2, and Desktop registration slots assemble the scenario. Where data is stored and where models run are two separate questions.

Positioning: teach parents how to teach

The product starts simply: a parent selects Homework Tutor from the template library and enters the child's name, grade and term, and math textbook edition, creating a dedicated tutor instance for that child . This version covers six primary-school subjects; configurable textbook editions and progress currently focus on math. Families with multiple children create separate instances with their own mistakes, learning records, and memory.

Send a homework photo. The system extracts each handwritten answer, identifies the subject, and branches according to whether each question was answered. Blank questions produce answers and explanations for parents. Completed questions are marked, and incorrect ones enter the mistake notebook automatically. Review is scheduled, due mistakes are delivered on Friday, and questions can be added to practice sets. Desktop works directly; after binding a DingTalk bot private chat, parents can send photos from phones too. There is no per-question OCR confirmation requirement: only unclear source facts that affect the conclusion need minimal clarification. Family groups, WeChat, and Feishu are outside this version's K12 integration scope.

This version develops photo handling in depth. Recognition preserves each question, the child's currently valid answer, and answer regions; crossed-out old calculations must not be mixed into the active answer. An initial classification is not permanent : when a sheet first classified as blank later yields clear mathematical answers, the program corrects the effective intent in the same transaction that saves source facts, preserving the original classification receipt. Blank questions give parents answers and explanations without inventing student answers or creating mistake/mastery evidence. Finalized completed question-based work retains an annotated original. Unreadable questions or missing/out-of-bounds coordinates receive text explanations rather than guessed red crosses; this does not justify omitting annotations for the entire completed sheet.

These choices follow three first principles:

• Grade correctness —use knowledge the child has learned. Grade and term come from the tutor profile; the current range is first grade's first term through sixth grade's second term. Math also uses curriculum references and linked textbook progress. Lookup, prechecks, and profile injection are deterministic; recognizing whether a solution exceeds the allowed level still involves model judgment. Keep hard guarantees hard and acknowledge soft judgments .
• Visible trust —retain evidence types and distinguish verification badges accordingly; homework marking presents the annotated original and per-question conclusions. Admit uncertainty rather than being confidently wrong.
• Give parents the answer and the explanation —a complete answer, solution process, and usable teaching sequence: what to ask, how to respond when the child gets stuck, and how to check understanding. Socratic questions are a parent's teaching method, not a barrier requiring parents to solve it themselves first.

Tutoring also retains an emotional gatekeeper : when signals such as “the child is crying / angry / fed up” appear, parent-facing guidance acknowledges emotion first—with empathy, recognition of effort, and smaller steps. Complete answers and lesson references remain available without an unlocking process. At nine or ten at night, the real obstacle is often unacknowledged emotion .

Why the AI can teach: pedagogy in Go and Markdown

Before the trust questions, answer the first question parents ask: what qualifies the AI to teach?

Backend v0.5.0-beta.1 ships the scenario package with a set of teaching Skills compiled into the binary and written to the service machine at first startup. Grade Boundaries and K12 Pedagogy form the foundation. Subject tutors focus on six primary-school subjects: math, Chinese, English, science, information technology, and art , supported by recognition/marking, reading, writing, vocabulary, and worksheet assembly. Subject tutors build on the foundation and inherit its boundaries. The manifest declares a Skill list generated from the bundled directory; two engine tools connect marking and review persistence ( k12_grade / k12_review ) to the tool loop.

They contain evidence-based teaching methods , rather than a vague instruction to be patient. The foundational Skill states its theoretical basis: stepwise teaching follows Vygotsky's Zone of Proximal Development and gradual release of responsibility (I do → We do → You do), alongside Rosenshine's Principles of Instruction: small steps, checks for understanding, and a high success rate. Emotional guidance follows Dweck's growth mindset : praise effort and strategies rather than intelligence or comparisons. Review combines retrieval practice and spaced repetition, also grounding the mistake-review ladder below. The Skill states the intended stance clearly: “You need not recite these terms to parents, but every action should be grounded in them.” These frameworks guide the design; they do not constitute empirical promises of learning outcomes.

Each subject adds its own methods. The math tutor follows Pólya's How to Solve It and its four steps —understand, plan, execute, review. Consolidation follows Gu Lingyuan's variation teaching from the Qingpu experience: vary numbers, situations, and questions to expose a stable underlying model rather than rote memorization. For a fifth grader, explain equations as adding or subtracting equally on both sides, not moving terms and changing signs. Essay feedback provides structure, material, and concrete revisions, with complete reference drafts for parents if needed while preserving the child's original. Art feedback starts from visible evidence and offers encouragement, questions, and one small next action, without inventing artistic intent. Pedagogy must become a sentence the parent can say and a step they can guide right now , rather than educational jargon pasted onto an answer. Skill acceptance criteria remain goals, not measured rankings.

For engineers, the reusable part is the two-layer architecture . This split began with an honest correction. Early research estimated that “90% of homework marking could be implemented through Skills.” Implementation revealed that the remaining 10%—grade boundaries, verification evidence, mistake state, and separation between children—determines whether the product is trustworthy , and none belongs solely in a prompt. Teaching capability is deliberately divided:

• Deterministic correctness belongs in Go —curriculum lookup and concept prechecks, input versions and source binding, numerical comparison and state transitions are compiled into the binary. The model does not decide these rules ; polished prompting cannot alter the judgment logic. Model-based recognition and explanation must not be presented as program guarantees.
• How to explain belongs in Markdown —explanation wording, Socratic questions, emotional guidance, and mappings from out-of-level language to grade-appropriate alternatives are injected at runtime into the system prompt. Readable, editable, and versioned , these mounted Skills let the community change wording and teaching flow, while actual behavior remains subject to the tutor persona and program contracts.

Soft constraints aim for good teaching; hard constraints enforce boundaries. Do not expect prompts to control what they cannot. The pattern of distilling human methodology into Skill files appeared in the former-lead Skill article ; here the subject changes from one person to a discipline's teaching methods.

The next three trust questions show where this release puts those constraints in code.

First checkpoint: what if the AI teaches it wrong? The verification-evidence chain

Start with a fact large-model vendors rarely put on their homepages: an LLM is not a calculator . It generates answer-like numbers by token probabilities and can fail probabilistically at multi-step arithmetic, sounding just as confident when wrong.

An arithmetic error may be tolerable in casual chat. Tutoring is different: parents use the explanation to teach their children . That is where the opening chain—AI error, mistaken teaching, mistaken learning—starts amplifying the mistake.

HexClaw joins two repeatedly studied academic approaches into an engineering chain: self-consistency sampling (Wang et al., ICLR 2023) improves solution accuracy, while program-aided verification (the PAL lineage, Gao et al., arXiv 2022 / ICML 2023, letting an interpreter execute computations) moves correctness checking from the model's assertions to deterministic execution.

Solver: argue with yourself first

Complex questions do not rely on a single generation. engine/solve.go contains two Solver reinforcement modes: self_consistency (sample the same method repeatedly and use a majority vote, capped at maxSelfConsistency = 5 to bound latency and cost) and method_diversity (deliberately solve with two different methods and check whether they converge).

Complexity routing selects the effort: long questions, multiple subquestions, and certain reasoning keywords raise solver strength; simple arithmetic avoids repeated sampling. The current implementation removes textbook appendices, printed examples, and already-selected individual question numbers from the copy used to judge complexity while preserving the full genuine question. That prevents layout text from promoting a simple problem into a “hard” one. An earlier fast path uses Go AST and big.Rat for exact arithmetic, simplest integer ratios, linear equations, and structurally clear fraction, unit-rate, and some geometry word problems. Incomplete structural recognition falls back to the model chain.

Verifier: the model supplies the program; the app executes it

A verdict should require more than another model glance. The latest code consolidates computational checks supported by the numerical comparator into an independent node. With a fresh context, the Verifier receives the question, complete candidate solution, and grade constraints, and supplies only a Python program plus stepwise audit JSON. The app then calls code_exec and reads the actual execution receipt. This removes the round trip in which the model decides when to call the tool and describes its result, without removing execution itself.

This comes from the actual adjudication code in engine/solve_verifier_node.go . Its order is meaningful: check grade scope, then process, then numerical values. “I checked it” is not execution evidence; the question's input digest, run ID, success state, exit code, and stdout must match. Other question types retain their existing tool loop, and the verification subagent may only execute code, without further delegation. The candidate solution remains in the input, so a fresh context does not imply information isolation. Understanding the question and semantically auditing steps still involve the model.

The verdict has four states, not two:

The fourth state, out_of_scope carries the educational constraint: even with a correct answer, a detected out-of-scope method is rejected —for example, simultaneous linear equations for a fifth-grade question. In a solving chain outside direct marking, explicit grade constraints and remaining budget allow one attempt to solve again within the grade, followed by full-process verification ; if it still violates constraints, OutOfScope remains. The reference combines profile grade and curriculum mappings. Built-in People's Education Press math keys mainly cover Grade 4 first term through Grade 7 second term; if a concept appears in several grades, the constructor keeps the earliest to avoid false scope violations. Secondary-school entries also help detect out-of-scope methods and do not open secondary tutoring in this version. The table is deterministic; identifying a method against the whitelist is still model-based semantic judgment, not a formal proof.

The practical change is making “did the judge actually calculate?” an inspectable fact instead of a prompt instruction. A model can write faulty code or misread a source, but without a successful execution receipt for this question, it cannot claim “Programmatically checked” . A later failed execution cannot borrow an earlier successful receipt either.

Numerical guardrails: do not entirely trust the judge either

Another easily missed defense asks: what if the code computes correctly but the model's verbal verdict contradicts it? The current guardrail normalizes comparable fractions, decimals, percentages, and supported quantity expressions, then compares them with answerTol = 1e-6 . Equal numbers have a precondition: when a complete solution is supplied, its process audit must explicitly pass before a verbal disagreement can be corrected. PROCESS: INVALID and OUT_OF_SCOPE cannot be erased by equal final values.

For parents: accidentally reaching the right answer does not mean every intermediate step is teachable. Marking distinguishes a wrong answer from a correct answer with a problematic process; the latter shows the step problem and explanation without automatically creating a mistake record. Answers that cannot be reliably parsed or compared remain uncertain; differing strings are not automatically arithmetic errors.

Audit the sentences parents will teach, as well as the answer

The parent guide has seven fields: answer, complete steps, grade-appropriate method, pitfalls, teaching order, follow-up questions, and checks. The solution and explanation may be generated together but remain candidates. The explanation binds to the chosen solution digest and receives its own itemized audit. A correct answer cannot validate a faulty worked example or misleading follow-up question . This is a model-content audit and must not be presented as numerical program proof.

Evidence honesty: execution and model judgment are different

The chain's final step preserves evidence strength honestly . There are six domain evidence types: numerical execution, symbolic execution, heterogeneous-model review, same-model heuristic, original-word reproduction, and none. The backend excerpt below judges strong trust. Badge-displaying entries distinguish Programmatically Checked from Cross-checked; not every result page displays a badge, and green alone does not establish evidence strength.

The section's most candid point is that Solver and Verifier use the same underlying model by default . Independence comes from fresh context and grounded program execution, not heterogeneous models. Agreement between two same-source models is only model-review evidence, not programmatic verification . And program-execution evidence needs further qualification: complex questions require the runtime to check this question's input digest, sandbox run ID, success status, and actual output ( CodeExecutionReceipt carries InputDigest and RunID), only a receipt matched to this question supports programmatic verification ; the deterministic fast path instead comes directly from evaluation. The original tool loop can supplement checks within budget. An independent computational-verification node without a valid receipt, with execution failure, or with an unknown call outcome retains its failure or unverified state. It cannot be packaged as successful verification. Parseable model judgments remain separate from execution evidence; unresolved disagreement remains uncertain. The same discipline keeps internal audit details out of marking output: mistake explanations remove the verifier's tick/cross self-checks and “whether...” self-questions, leaving one human-readable cause for the parent . Verification scratch work stays out of the interface.

A shared model does not mean any model will work. A durable K12 marking task currently freezes the selected model at creation, requiring both image and text support . Recognition, solving, and verification keep that route without silently switching midway. General solve uses a separately configured reasoning model only when provider/model were not explicitly specified. Seeing images does not guarantee good marking; model capability remains a prerequisite throughout.

Extract correctness from a model's confident tone and turn it into inspectable evidence— that is the engineering boundary between tutoring and chat .

From a chat request to a durable task: recovery is more than rerunning

A homework photo passes through recognition, solving, verification, finalization, and delivery. The system first saves the original-image reference, source digest, model route, request digest, and stage budgets. Physical calls distinguish prepared, sent, succeeded, and outcome_unknown. Recovery reuses completed units and resumes only from known safe checkpoints; when a sent request has an unknown result, check the original request before resending . Page state and service task state are separate; closing a page does not cancel a durable task.

What a question bank can save—and what it cannot

Distinguish textbook grounding, cross-task question assets, and reuse within the same task. verified_text means direct reading of verified textbook text, freezing the textbook, page, and source digest to establish where evidence comes from. Question assets match reliable facts such as question text and grade, retain versions and adoption receipts, and reuse verified solutions. Within one task, an already verified solution goes to the grader to compare with the student's answer rather than being solved again. A matching answer asset cannot skip current-image recognition or assessment of the student's answer and steps , nor overwrite the ledger of an earlier unresolved call.

Trust has a cost. General solve has a default five-minute wall-clock guardrail, while durable K12 marking uses frozen stage budgets. A local installed-app report from October 3, 2026 found that one complete DingTalk workflow for a messy math assignment took 285.507 seconds, including 248.214 seconds for recognition review, missing the 120-second target . That run used gpt-6-sol, fully processed 16 questions, and actually delivered both text and annotated PNG. It proves only that sample, model, and installed version—not an accuracy ranking or performance for every model. Saving solver calls does not remove the slowest recognition stage.

Second checkpoint, part 1: where mistakes live—record primitives and a spaced-review engine

Incorrectly marked questions enter the mistake notebook automatically. Initially, they used a domain-neutral record primitive agent_records (storage migration V8). As domain constraints became clearer, typed tables such as k12_mistakes, k12_accumulations took over in V9, with a scenario-installation ledger in V10 and deduplication-key backfill in V11. The record contract is general; domain fields have their own home .

The contract still uses collection to distinguish collections. Typed tables retain generic columns such as status (state machine), due_at (due scheduling), and version (optimistic locking), while questions, answers, and mistake causes occupy explicit domain columns. Three details are reusable:

• Database constraints and same-question matching jointly handle idempotent deduplication —typed tables have UNIQUE(agent_name, dedupe_key) . Mistake keys combine the source session with normalized question text, absorbing whitespace and capitalization differences in OCR. Collections deduplicate by subject, type, and normalized content. Marking also matches a unique exact existing mistake source for the current child, then updates its review result. The database key alone does not promise global uniqueness across sessions .
• The isolation key is an immutable primary key —on the agents(name) foreign key. Renaming changes display_name; schema enforces isolation across children/instances, and deleting an instance cascades to its data.
• A second use demonstrates the generality —the Chinese/English Collection notebook, storing dictation mistakes, useful words and sentences, and poems, is another collection under the same contract, persisted in its own table.

Mistake sources are not limited to in-app marking. A parent can add a teacher's oral feedback, a workbook question, or something the child says they did not understand through Record a Mistake . Save the question and child's answer; if the cause is blank, one lightweight reasoning call summarizes it in a sentence , then schedules review as usual. This path deliberately skips the adversarial verification chain . It records a question already known to be wrong rather than judging correctness, avoiding full-chain latency merely to keep a record.

For scale, the earliest research estimated about 450 records per school year on one machine . This is a single-user Desktop design scale, not a measured capacity ceiling. Household cloud sync or multiple users would require revisiting pagination, incremental sync, and conflict handling together. A single-machine design does not scale sideways unchanged .

The review engine: four intervals that lengthen with correct attempts

Mistakes have five states: new / explained / retried / mastered / archived . They normally advance from new to explained to retried to mastered; failed spot checks return them to review, and archived records can be restored. A few core lines drive this:

In plain terms: a new mistake is due after one day; the first correct retry schedules it three days later. When the system re-marks it correct, a record already in retried with a previous correct timestamp and a gap of at least three days can become Mastered and leave the queue. This fixed state-and-time rule does not strictly check “two consecutive correct answers” . Before mastery, the ladder advances through 1 / 3 / 7 / 14 days, capped at 14. Unmastered questions do not hide simply because they have not been practiced for a while. Generated variants on the same concept must themselves pass the verification chain before entering a printable practice set.

Anki and SuperMemo users will recognize the spaced-repetition structure. The 1/3/7/14 values are product-defined fixed intervals inspired by the scale of spaced-repetition research, not original Ebbinghaus experiment data or an SM-2-style dynamic difficulty factor. For tens or hundreds of mistakes per child per term, this fixed ladder is a reasonable complexity tradeoff while completing the workflow.

Parents see a few lightweight actions: Review This Week queues due mistakes. After adding them to a Practice Set , print or send it, let the child answer, and return a photo for system re-marking and rescheduling. Parents can manually record results to advance review, but system mastery still depends on verified actual answers. Misrecognized source work can be corrected and re-marked through an immutable correction chain : each correction appends a historical final artifact instead of overwriting it. If the unique mistake record it created is no longer valid, the system withdraws it while preserving the audit. Correcting a source does not count as the child's practice . Learning profiles export to PDF, Word (.docx), and Markdown . PDF uses the platform render service's pandoc + typst layout; practice sets separately provide question and answer sheets for printing and PDF saving.

One subject-specific detail: Chinese dictation and English vocabulary use verbatim (original-word reproduction) evidence, taking the reference answer directly from the saved original . Collections can generate dictation or gap-fill questions for practice sets, with photographic answer return and re-marking. Faithfulness to the original at question generation is not proof that the child answered correctly; student answers follow a separate marking chain. Evidence types extend by subject rather than being math-only.

Parents can skip ahead : the next two sections, on the egress gateway and scenario architecture, are for engineers. Parents interested mainly in practical use can jump to “An honest look: this version's boundaries” and then follow the screenshots in the companion “A Calmer Homework Routine” guide .

Second checkpoint, part 2: does the child's data leave the network? A fail-closed egress gateway

First, state the product position clearly: where data is stored and where the model runs are separate questions . The default local service stores mistakes, learning records, and profiles in local SQLite, with original images, textbooks, and backups on the same machine. After switching to a cloud service, that service manages conversations, learning records, models, and DingTalk connections. Switching does not migrate data automatically. Now distinguish the outgoing paths:

• Model calls —depend on the provider configured in the current service. Only the corresponding calls from a local service to a local model stay on this computer; a “local model” in a cloud service runs on that server.
• Sensitive data categories: child profiles, homework photos, mistake records, and learning memories —cloud-model calls are checked by purpose and data class. The allowlist permits necessary data for recognition, explicitly attached-image chat, and solving/verification. Local storage does not mean model calls stay offline; what is sent depends on purpose and the chosen model.
• IM delivery —sending practice sheets or reminders to a bound DingTalk private chat sends content to the IM provider. This third-party channel is enabled by the user, controlled by the user, and outside the egress gateway's scope.

Another distinction matters: this policy decides whether HexClaw permits the request . Once data legitimately goes to a cloud vision/model provider or IM provider, its retention and use follow that provider's terms. HexClaw cannot control that and does not pretend otherwise.

The current egress package defines nine Purposes and six DataClasses. Its fixed purpose table grants the necessary classes separately for recognition, explicitly attached-image chat, solving/verification, and profile maintenance. Do not omit this branch : when memory is actually enabled for the current chat, general_chat / vision_chat may carry memory. That setting belongs only to this request and is not inherited by new subrequests. An allowlist table does not justify claiming that learning memory never leaves the machine.

At K12 call sites, these four classes map to child profiles, homework photos, mistake/collection records, and learning memory. But that mapping exists only at the call site ; the egress package contains no domain terminology. The third checkpoint explains why that matters.

The key property is fail-closed : every outgoing request declares its purpose and data classes in its context. Request envelopes do not inherit a parent's declaration, preventing purpose drift. At the gateway, requests without an envelope or with empty data classes are blocked . Forgetting to declare blocks the request rather than silently bypassing the gate. This Guard sits on real vision, chat, embedding, and cron-compilation call sites. Its scope must be stated precisely: the call chain toward cloud models , not a system-wide operating-system network gateway. Call sites annotate data classes; there is no automatic content classifier.

The gateway makes a call's purpose and data classes explicit and its decision inspectable. It is not proof that data never leaves the machine, nor a substitute for explaining service location, enabled memory, and third-party delivery.

Third checkpoint, for architects: will adding K12 damage the platform?

This is the release's largest architectural investment and its most reusable lesson for teams combining general platforms with vertical products.

The risk had already materialized. In an earlier exploration, domain terms such as mistakes, review, and exam preparation spread into multiple platform files across engines, APIs, and adapters. Every scenario would grow more if inside the core until three scenarios made it unmanageable. Backend v0.5.0-beta.1 repaid that debt around a single mechanism: Scenario Pack + six injection seams .

A less technical analogy: imagine the platform as an exhibition center . It hosts no event of its own but provides standard connections : power, load-bearing rigging points, networking, stage-lighting lines, and ticket gates. Today's wedding and tomorrow's product launch use the same venue wiring; organizers bring flowers, signs, and schedules to connect. K12 is the first event. HexClaw's connections are laid out in this scenario.Registry:

The mistake-notebook schema, grade allowlist, and scenario buttons enter through Records / Constraints / Buttons. The six seams now have an outer Manifest v2 that declares scenario version, capabilities, mount points, dependencies, and scheduled workflows. Install validates and registers resources, returning an installation receipt. Uninstall uses that receipt to remove this scenario's resources while retaining business data. The venue has both standard connections and entry/exit inventories. Three rules are falsifiable , stronger than a verbal layering guideline:

• Purely declarative assembly ——Assemble(*Pack) performs registration only; a code comment states the rule: no business branching such as if pack == k12 .
• Domain rules stay together; the composition root wires them —mistake, review, and learning-state rules live mainly in scenarios/k12/ , with wiring in the composition root. The current cmd/hexclaw/ contains several K12 adapters. K12 routes mount through the generic srv.Mount("/api/k12", …) , so the general router only mounts handlers. The engine still contains parent-explanation output and audit protocols, however; the layering goal must not be described as eliminating every domain semantic.
• Removability is the acceptance criterion —remove scenarios/k12 and the corresponding assembly/adapters from the composition root, and the platform must still compile and run independently. The expectation is: when the event leaves, the venue becomes empty again and can host something else tomorrow . Conversely, attach a mock scenario filling all six seams to the empty platform and check whether the core needs changes—an empty-event rehearsal that checks every connection. Internally, this is the AP-1 bidirectional gate . More precisely, it is a source-level, compile-time assembly boundary , not a user-facing hot-pluggable marketplace.

Desktop mirrors this structure: src/contracts/ (contracts, with a top-level barrel strictly free of domain terms) + src/shell/ (a domain-neutral general shell) + src/features/k12/ (scenario packages). The frontend scenarioRegistry provides fourteen domain-neutral registration slots for view descriptors, record schemas, identity projections, conversation enhancements, agent-card extensions and badges, profile templates, webhook management, ambient presentation, appearance settings, scheduled-task display, and more. Vue dynamic components render chat enhancements from view descriptors . Header tabs, message badges, and record views are registered by the scenario package. Frontend registration is mainly static; backend GET /api/k12/view-descriptor currently supplies mostly composer shortcuts dynamically. Scenarios assemble mainly through extension mechanisms such as <component :is> . ChatView still directly retains K12 image-attachment identity and reading adapters, however; the registration slots exist, and residual coupling exists too . The source-removal boundary still needs actual build acceptance. VS Code extension users will recognize contribution points: the platform defines seams, scenarios declare contributions, and runtime assembles them .

Why invest so much? K12 is a flagship, not the destination. Whether the next pack is a fitness coach or legal assistant, platform-side code changes should approach zero . That is the test of whether a general platform with vertical scenarios can endure.

“Approach zero” is abstract. Fill the same seams with an unrelated domain to see the flexibility more concretely. Consider a legal consultation assistant as an illustration— a proposal, not a released scenario pack —with all six seams taking different content:

With the same scenario.Registry , if existing contracts can express the right-hand column, resources need only be declared in scenarios/law/ and registered in the composition root. That is the precise code-level meaning of a general foundation producing a vertical product : solving/verification, record contracts, egress, cron, and evaluation are platform mechanisms; mistakes versus causes of action, and grades versus limitation periods, belong to scenario packs.

The cost is real: six seams add indirection, descriptor protocols need maintenance, and the mock pack needs testing. Until a second pack exists, its generality remains a hypothesis to validate through another real scenario . The investment bets on at least two scenarios; otherwise it may be overengineering. Making AP-1 falsifiable lets us discover that promptly.

In the wider landscape, this mechanism targets a third layer: MCP answers “What can the agent call?” through a common tool/data-source protocol; Agent Skills answers “How should it work?” through portable procedural knowledge; while scenario packs ask “How does it become a domain product?” Beyond tools and prompts, that means assembling UI, business state, hard constraints, evidence, automation, and evaluation. This is HexClaw's own engineering abstraction, not an industry standard. It explains why installing several K12 Skills is not equivalent to delivering a parent-tutoring product.

Add automation: due mistakes arrive Friday at 7 p.m.

Mistakes and review queues are ready; the last hurdle is parents forgetting to open the app. Backend v0.5.0-beta.1 creates four default cron tasks when the tutor instance is created:

Delivery follows the Starlark sandbox-script approach from the digital-workhorse article , but these scripts have no LLM involvement : they periodically use http_get to call K12 delivery endpoints in the current service, sending content to the bound DingTalk private chat or Desktop only when available; empty content is silently skipped . On Fridays with no due mistakes, parents receive no empty “No mistakes this week!” notification. The idempotency key is instance name / task type, keeping children's reminders separate. Friday tasks organize and deliver due mistakes; parents add practice sets as needed. Local cron requires the computer and HexClaw service online; cloud-service mode requires the server online, so turning off the computer does not stop cloud tasks.

The last mile to a phone also needs evidence. One click on Send to Phone delivers to the tutor's currently valid bound targets; text, annotations, and other attachments each retain their own status. Platform acceptance is not parental receipt; all necessary components must arrive for the batch to count as delivered . Query the original batch when results are unknown; recover only explicitly failed items.

Automatic image-task return follows the same artifact-completeness rule: blank worksheets send answers and explanations; completed question-based work sends text and actual annotated images. A successful request cannot conceal a missing image. Essays and art send feedback text.

Tutoring content follows the same source discipline: textbook support, AI synthesis, local records, program checks, and learning signals are labeled separately. Essay and art feedback starts from visible evidence and offers encouragement, questions, and one next action. Unknown sources must not impersonate textbook authority.

An honest look: this version's boundaries

As usual, separate implemented mechanisms from the boundaries that remain:

• Curriculum references and textbook progress are different . Built-in curriculum tables focus on People's Education Press math. Math textbooks can currently be linked with unit, lesson, or page progress. Other primary subjects follow the profile and teaching Skills, without equivalent textbook-progress configuration.
• Original-image marking still depends on source and location quality —completed question-based work must deliver a genuinely annotated original. Questions without reliable coordinates keep text explanations rather than guessed marks. Blank worksheets give explanations without manufacturing annotated images.
• Program checks preserve process and scope vetoes but are not formal proofs —real receipts prove execution and numerical results. Question interpretation, fidelity of model-generated code, semantic step audits, and teaching outcomes each have separate limits.
• Recognition and re-marking still depend on source quality —blurred originals, missing question text, and unclear handwriting affect conclusions. Correct the source and re-mark using the new input; source correction does not count as the child's practice.
• Solver and Verifier share a model by default . Heterogeneous review seams exist: heterogeneous_model evidence is strong only when solver ≠ verifier. Current same-model agreement is not execution evidence, which is why badges avoid claiming “double verification.”
• Marking accuracy and speed depend on the chosen model . Local and cloud providers are configurable, and image tasks need an actually selected vision-capable model. Outcomes vary by model, hardware, and assignment type; provider rules determine cloud-call charges.
• The review engine is a fixed ladder , not an adaptive algorithm with SM-2-style difficulty factors. It suits the notebook's scale, but its simplified nature must be explicit.
• Continuous operation requires the current service online —local mode needs the computer and service running; cloud mode needs the server and relevant models available. Each side keeps its own data; switching does not migrate it automatically.
• The complete workflow still has a performance bottleneck —the 120-second target remains unmet. Successful samples do not establish success across every model, image quality, or deployment.

This release goes beyond K12

K12 is the main feature, but making it work also produced platform changes useful to people without children:

• 🛡️ Consolidated execution primitives —code/command execution centers on code_exec, with timeout, resource, and receipt management. Legacy code / shell are deprecated but retain configurable compatibility entries and have not been fully removed from source
• 🧩 Scenario injection infrastructure —the six-seam Registry, engine scenario injection and reply-metadata channel, and generic Mount hooks are platform mechanisms reusable by a second pack
• 📦 General records + egress gateway —records contracts and egress policy are not K12-specific. Structured records and controlled cloud-model calls use general mechanisms; K12 typed tables remain in the scenario data layer
• 🖥️ Three-part Desktop scenario extensions —contracts / shell / features layering plus backend view descriptors let scenarios register their own interface enhancements
• 📚 Backups and exports preserve actual assets —.hexbak checks integrity with SHA-256. Learning profiles cover weekly review, mistakes, practice sets, collections, and work. PDF / Word save frozen server artifacts directly. Markdown with attachments is a ZIP containing archive.md, manifest.json, and originals. Practice sets separately provide question/answer printing and PDF saving.
• 📖 Textbook grounding and question-asset reuse —direct textbook reading establishes the source; qualified assets identify solutions that need not be recomputed. Neither replaces recognition and judgment of this student's current answer or promises an entire page in seconds.
• 🌐 Local and cloud forms —the backend can run beside Desktop or as a single-instance cloud service. DingTalk tutoring follows the bound service; data location and availability follow the deployment.

Three forward-looking judgments remain. The next verification step is a genuinely heterogeneous Verifier . The seam exists—different solver/verifier models are required for strong evidence—but second-model routing and evidence production still need to be connected. Curriculum tables can extend through Constraints for other editions such as Beijing Normal University and Jiangsu Education Press. And the six-seam architecture must wait for a second pack to complete its falsification test . Only if it holds does the opening question receive a real answer: a general platform can produce a trustworthy vertical scenario without contaminating its core , completing that platform-plus-scenario route. Domains change; the discipline remains: separate probabilistic intelligence from deterministic constraints, results from evidence, facts from profiles and documents; keep scenario semantics in packs; turn every conversation into an executable next step rather than burying it in chat history.

Photo question search gives a child an answer. Parents need the twenty minutes that help the child understand it.
A calmer homework routine takes more than more fluent AI—
it needs evidence when right, honesty when wrong, traceable mistakes, and connected review.

This article explains why it can be trusted; how to start—download, create a profile, and send the first homework photo— is covered step by step in the companion “A Calmer Homework Routine” guide with screenshots.

Further reading —earlier articles in the HexClaw series:

1. Raising a Digital Workhorse —compile a sentence into a self-healing sandbox script, the foundation for this article's cron delivery
2. Former-lead Skill —distill methodology into a Skill file, the same pattern used for teaching Skills here
3. Loop Engineering —the four-generation framework from Prompt to Loop
4. Agent Memory That Dreams —the memory system behind learning profiles
5. v0.4.0 Uyghur Localization —engineering notes on Uyghur localization
6. Architecture Deep Dive —one developer × Claude Code × a six-repository ecosystem

References

• HexClaw AI ecosystem repositories: github.com/hexagon-codes
• Wang et al., Self-Consistency Improves Chain of Thought Reasoning in Language Models , ICLR 2023 (self-consistency sampling and majority voting)
• Gao et al., PAL: Program-aided Language Models , arXiv 2022 / ICML 2023 (delegating calculation to an interpreter)
• Ebbinghaus forgetting curves and spaced repetition: SuperMemo SM-2 algorithm (1987), Anki documentation
• Pedagogy: Pólya, How to Solve It (1945); Rosenshine, Principles of Instruction (2012); Dweck's growth mindset; Vygotsky's Zone of Proximal Development; Gu Lingyuan's Qingpu experiment and variation teaching
• VS Code Extension API · Contribution Points
• Industry learning modes: Anthropic《Introducing Claude for Education》(2025-04-02)· OpenAI《Introducing study mode》(2025-07-29)· Google《Guided Learning in Gemini》 (August 6, 2025), all official announcement pages
• Zhejiang Publicity, Zhejiang Provincial Party Committee Publicity Department: “Why Does Homework Tutoring Make Parents Angry and Frantic?” (reprinted by Zhejiang Online, February 3, 2026); China Youth Daily: “How Can Parents Escape Homework Tutoring Anxiety?” (April 13, 2021, reprinted by People's Weekly)

Source index: engine/solve_verifier_node.go (independent verification), engine/solve.go (process vetoes), scenarios/k12/usecase/grading_problem_assets.go (question assets), egress/egress.go (egress decisions); Desktop src/shell/scenario/registry.ts (14 slots), ChatView.vue (asset adapters), features/k12/export.ts (exports).

HexClaw
Deploy locally or in the cloud · Control your data · Free and open-source software
Website: hexclaw.net  |  GitHub: hexagon-codes
Weibo: @HexClaw  |  X: @hexclawapp
Email: [email protected]