Creation Tools — Single Flow (Form → Generate → Artifact)¶

Status: Accepted design, pre-implementation · 2026-07-12 Supersedes: the chat-first entry model in Document Editor & Generation (the two-pane editor design there survives; the entry point changes) Mockups: interactive design spec reviewed and approved 2026-07-12 (Claude artifact creation-tools-flows)

Every artifact a trainer creates follows one path: a structured intake form → generation by a specialized agent → an editable artifact. Chat never generates artifacts; it hands off to the form. This replaces the current model where dashboard chips ("Lesson plan", "Slide deck", "Question bank") open an empty chat and the trainer must describe duration, semester, subject, structure, and grounding in prose every time.

Why this exists¶

Who asked? Self-initiated (founder), triggered by direct comparison against MagicSchool's lesson-plan tool. The June agent-document-editor doc passed the Gate with validation flagged WEAK (no trainer interview) — that flag carries over.

What pain? A trainer on /teach clicks "Lesson plan" and gets an empty chat. To get a decent plan she must remember to type duration, semester, subject, structure, and grounding into prose every time. The system collects zero structure, so output quality is a lottery: "otherwise difficult to generate high quality lesson plans, presentations, question banks."

Cost of not doing it? The north star for teacher tools is repeat weekly use. Low-quality first drafts → trainers try once and don't return → the teacher-tools surface fails at pilots (the VIT trainer persona is exactly who is at risk).

Validated or a guess? Partially validated: MagicSchool's form→document pattern is market-proven at scale, and the pain is observable in our own UI. No direct faculty interview yet — get one trainer to use Phase 1 before stamping the pattern.

How will we know it worked? A trainer completes a form in under a minute, gets a draft she edits rather than regenerates, and comes back next week. Sean Ellis counterfactual: remove the forms a week after shipping and trainers would specifically complain about having to re-explain context in chat.

The single flow¶

flowchart LR
  subgraph Entry points
    A[Dashboard chip]
    B[Create tile]
    C[Composer text]
    D[Chat handoff card]
  end
  A --> E["/create/:tool intake form"]
  B --> E
  C -->|seeds Topic field| E
  D -->|pre-filled| E
  E -->|structured payload| F[Specialized agent<br/>chatbot repo, one per tool]
  F --> G["/artifacts/:type/:id<br/>artifact editor"]

Retired paths:

Chat generating artifacts — lesson_plan / question_bank / presentation are removed as chat generation modes. Chat detects a creation ask and replies with a pre-filled "Open in builder" card (see Chat handoff below).
/documents/new — the orphan quick-assignment form is retired (redirect). Both the dashboard Assignment widget and Assignments › New in the sidebar land on the same Compose → Review → Proctor wizard at /assignments/new.

Assignments are the deliberate exception: their intake is the existing wizard (it is the form), and their output lives in Assignments, not Artifacts — assignments are operational (targeting, proctoring, grading), not documents.

Intake forms — shared skeleton¶

Routes: /create/lesson-plan, /create/question-bank, /create/slide-deck (trainer-only routes). Each form is the shared skeleton plus tool-specific fields:

Teaching context (optional, course-first) — dropdown of the faculty's actual teaching allocations ("Mathematics · B.E. Sem 3 · CSE-A"), sourced from course assignments. One selection carries subject, program/branch, semester, section, and linked KB. This is the structural advantage over MagicSchool's free-text "grade level". While "No specific course" (the default) is selected, the control progressively discloses two optional structured fields — Subject (org subject catalog; free-text fallback when the catalog is empty) and Class or semester (Class 1–12 for schools, Semester 1–8 for colleges) — feeding the backend's existing subject/grade_level no-course path, so course-less generations are still grounded and the KB grounding filter still applies. Observed while testing: teachers with no allocated courses dead-ended, and a course is just one container for what actually keys a generation — subject + class/semester + objective. Objective-only generation (no context at all) is valid.
Topic / objective (required) — free multi-line text (auto-grow textarea, 500-char cap shared with the chatbot agents' topic param). If the trainer typed in the dashboard composer, that text arrives as a visibly-marked editable seed; overflow beyond the cap seeds "Anything else?".
Tool-specific fields (see below).
Grounding (optional, never a gate) — KB materials filtered to the selected course (textbook chapters, syllabus units, uploads), pre-checked by topic relevance. Flexible by design: if the course has no syllabus/textbook in the KB, the section collapses to an upload dropzone and generation runs from the topic alone. Ad-hoc file upload always available.
Show an example — exemplar output link (MagicSchool-style) to set quality expectations.
Generate — streams into the artifact editor.

Tool-specific fields¶

Tool	Fields
Lesson plan	Duration (30/45/60/90 min) · session type (lecture / lab / tutorial / flipped) · free-text criteria
Question bank	Question count (stepper) · types (MCQ / short / long / numerical / T-F) · difficulty preset (easy-leaning / balanced / exam-hard → mapped to ratios in the payload) · Bloom emphasis
Slide deck	Length (8/12/16/20+ slides) · depth (introductory / intermediate / advanced) · style (visual-first / text+diagrams / detailed notes)
Assignment	The existing `/assignments/new` wizard fields — unchanged

Specialized agents (chatbot repo)¶

Each widget maps 1:1 to a specialized agent in kwiloai_chatbot (pydantic-ai, built to the proven mock_test specialist pattern): lesson_plan, question_bank, presentation. The form's structured payload is the agent's typed input — no prose-prompt parsing. Grounding uses /kb/search best-effort.

Boundary unchanged from the chatbot agent platform direction: webapp = policy layer (auth, RBAC, quota, entitlements, is_ai_generated labeling, result persistence), chatbot = LLM layer (all prompts, generation, RAG, token usage).

Output: artifacts with a two-pane editor¶

Generated lesson plans and question banks become new artifact types in the federated Artifacts library, with a detail route in the /artifacts/:type/:id pattern:

Right pane: editable TipTap document (existing NotionEditor); edits autosave.
Left pane: refine chat scoped to this artifact ("make the guided practice group-based") — edits patch the document in place, highlighted. This is the only "chat" in the creation flow, and it belongs to the artifact, not the AI Tutor.
Provenance line (permanent): teaching context, AI-generated label (DPDP), grounding sources.
Actions: Export DOCX / PDF / MD · Attach to course · Save.

Slide decks stay on the existing /presentations/:id viewer (already an artifact); only the intake form is new. The Artifacts list renders one full-width row per artifact (type badge → title → meta), not a card grid.

Role-scoped visibility¶

Artifacts are owner-scoped (existing behavior) and type-scoped by role — enforced in the backend federation endpoint (a learner hitting a lesson-plan URL gets 404), not just hidden tabs:

Type	Trainer / Faculty	B2B Learner
Lesson plan	✅	—
Question bank	✅	—
Slide deck	✅	—
Research	✅	— (not offered to B2B learners today)
Images	✅	✅
Study plan	—	✅
Mock test	—	✅

Creation routes are role-scoped the same way: /create/* is trainer-only; learners never see those chips/tiles.

Chat handoff (no dead ends)¶

Users will still ask chat to "create a question bank on stacks and queues, ~20 questions". Chat parses the request into form fields and replies with a pre-filled "Open in builder" card (context, topic, count) that deep-links to /create/question-bank. One flow preserved; no inline generation, no refusal dead-end.

Phasing¶

Lesson plan end-to-end — form → lesson_plan agent (today a placeholder, KWILO-CHATBOT-11) → artifact editor + new backing table + federation registration. Defines the pattern. Get one trainer using it before stamping.
Question bank — second agent; reuses form skeleton, editor, table.
Slide deck — intake form bolted onto the existing presentation pipeline. Cheapest.
Assignment consolidation + chat handoff — retire /documents/new, wire handoff cards across all tools, remove creation modes from chat.

Non-goals¶

No tool-library IA — no "Tools" sidebar section with a card per tool (MagicSchool's model). The dashboard + chips remain the entry surface.
No in-chat form widgets — forms are dedicated pages, not chatbot-rendered inline forms.
No chat generation power-path — keeping inline chat generation "for experts" would re-create the two-path problem this design exists to kill.
Assignments are not artifacts — they keep their own home and lifecycle.
Research intake stays conversational — it is genuinely a dialogue; output is captured as an artifact as today.
No AI parsing of composer text in v1 — the composer text carries into the Topic field verbatim; field-level parsing can come later.

Rejected alternatives¶

Alternative	Why rejected
Full tool library (MagicSchool clone)	Duplicates the dashboard's job; demotes chat entirely; more IA churn than the pain justifies
Smart forms inside chat	Heavy chatbot/frontend widget work; cramped for grounding pickers; keeps quality hostage to conversation flow
Keep chat generation alongside forms	Two paths to the same artifact = unpredictable quality and the exact confusion this kills
Course required on every form	Blocks legitimate one-off use (guest lecture, workshop) and new users with no allocations
Explicit context mode tabs (by course / by subject / free-form)	Forces users to name their situation before describing it; progressive disclosure under "No specific course" carries the same payload with less IA
Free-text grade/audience fields (MagicSchool-style)	Wastes Kwilo's structural knowledge of who teaches what
Assignments in Artifacts	Assignments are operational objects with targeting/proctoring/grading, not documents

Changelog¶

2026-07-14 — Teaching context decoupled from courses: "No specific course" (the default) now progressively discloses optional Subject + Class/Semester fields wired to the backend's existing subject/grade_level no-course path; grounding filter follows the manual subject; topic/objective became a multi-line auto-grow textarea (cap stays 500 — the chatbot agent params cap topic at 500, so raising it needs a coordinated chatbot-first deploy). Webapp PR kwiloai_webapp#1364. No backend change. Gate context: pain self-observed while testing (partially validated) — teachers without allocated courses dead-ended; success = course-less generations happen, first-session artifacts before any course exists, richer multi-line objectives.
2026-07-14 — Phase 4 (chat handoff) implemented — the spec is now fully built: webapp PR kwiloai_webapp#1361 (handoff policy, CreationHandoffCard, prefilled builder launch, /documents/new retired) and chatbot PR kwilo-chatbot#92 (creation_handoff tool + SSE event). Deploy chatbot STRICTLY first (webapp-first = 422 on all B2B teacher chat). Scope decisions: teacher chat mode chips kept (they hand off rather than generate); handoff gated to B2B instructors; presentation mode chip's inline path noted as a follow-up decision.
2026-07-13 — Phase 3 (slide deck) implemented: webapp PR kwiloai_webapp#1348 (/create/slide-deck with in-form streaming progress, /presentations/new retired for instructors) and chatbot PR kwilo-chatbot#90 (slide_count/depth params, shared document-filtered grounding). Two recorded deviations from the original design: style options expose the agent's real lecture/interactive/summary capabilities instead of the mockup's visual-first taxonomy; /presentations/new stays for B2C/admin roles who legitimately use it. Stacked on Phase 2 PRs; chatbot deploys first.
2026-07-13 — Phase 2 (question bank) implemented: webapp PR kwiloai_webapp#1346 (intake form at /create/question-bank, shared TeachingContextSelect/GroundingSection, whole-bank refine, two-pane editor with header publish) and chatbot PR kwilo-chatbot#89 (bloom emphasis, document-filtered grounding, revision). Stacked on the Phase 1 QA PRs (#1342/#88); chatbot deploys first.
2026-07-12 — Phase 1 (lesson plan end-to-end) implemented: webapp PR kwiloai_webapp#1339 (intake form, structured request + course/grounding resolution, whole-doc refine, editor renderer + refine panel, artifacts tab) and chatbot PR kwilo-chatbot#87 (structured agent params + revision mode). Deploy chatbot first — the webapp sends the new param keys unconditionally. Deliberate v1 gaps: no "Show an example" link, whole-doc revision (not per-block patches), grounding = title hints + agent-side retrieval (no ChunkSet packing).
2026-07-12 — Initial accepted design. Supersedes chat-first entry in agent-document-editor.md; that doc's two-pane editor concept is folded in here as the artifact editor. Design reviewed via interactive mockups; refinements incorporated: flexible grounding (works with zero KB materials), full-width artifact rows, 1:1 widget→agent mapping, single assignment intake, role-scoped types (learner research excluded for B2B, trainer images included).