feat: add artifact feedback component and related hooks

- Introduced `ArtifactFeedback` component for rating reports, quizzes, flashcards, and infographics.
- Implemented feedback reasons and comments for user ratings.
- Added `suggestTemplates` and `prefetchSuggestions` hooks for report template suggestions.
- Created `useArtifactLimits` hook to manage artifact limits from server settings.
- Added new infographic images: midnight.png and paper.png.

backend/alembic/versions/0021_artifact_feedback.py

@@ -0,0 +1,40 @@
+"""artifact_feedback: thumbs up/down on generated reports, quizzes, flashcards and infographics
+
+Revision ID: 0021_artifact_feedback
+Revises: 0020_calendar_kit
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0021_artifact_feedback"
+down_revision = "0020_calendar_kit"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 0001 builds from the live models, so a fresh database may already have the table.
+    if "artifact_feedback" in sa.inspect(op.get_bind()).get_table_names():
+        return
+    op.create_table(
+        "artifact_feedback",
+        sa.Column("id", sa.Uuid(), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("workspace_id", sa.Uuid(), sa.ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("artifact_id", sa.Uuid(), sa.ForeignKey("artifacts.id", ondelete="SET NULL")),
+        sa.Column("user_id", sa.Uuid(), sa.ForeignKey("users.id", ondelete="SET NULL")),
+        sa.Column("artifact_type", sa.String(30), nullable=False),
+        sa.Column("rating", sa.Integer(), nullable=False),
+        sa.Column("reasons", sa.JSON(), nullable=False),
+        sa.Column("comment", sa.Text()),
+        sa.Column("snapshot", sa.JSON(), nullable=False),
+        sa.UniqueConstraint("artifact_id", "user_id"),
+    )
+    op.create_index("ix_artifact_feedback_workspace_id", "artifact_feedback", ["workspace_id"])
+    op.create_index("ix_artifact_feedback_artifact_id", "artifact_feedback", ["artifact_id"])
+
+
+def downgrade() -> None:
+    op.drop_table("artifact_feedback")

backend/alembic/versions/0022_report_template_cache.py

@@ -0,0 +1,34 @@
+"""report_template_cache: suggested report templates kept, so the Create report dialog is instant
+
+Revision ID: 0022_report_template_cache
+Revises: 0021_artifact_feedback
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0022_report_template_cache"
+down_revision = "0021_artifact_feedback"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 0001 builds from the live models, so a fresh database may already have the table.
+    if "report_template_cache" in sa.inspect(op.get_bind()).get_table_names():
+        return
+    op.create_table(
+        "report_template_cache",
+        sa.Column("id", sa.Uuid(), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("workspace_id", sa.Uuid(), sa.ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("key", sa.String(64), nullable=False),
+        sa.Column("templates", sa.JSON(), nullable=False),
+        sa.UniqueConstraint("workspace_id", "key"),
+    )
+    op.create_index("ix_report_template_cache_workspace_id", "report_template_cache", ["workspace_id"])
+
+
+def downgrade() -> None:
+    op.drop_table("report_template_cache")

backend/alembic/versions/0023_drop_brand_kit.py

@@ -0,0 +1,31 @@
+"""drop_brand_kit: the brand kit (workspace colors and logo, and the plan flag for it) is gone
+
+Revision ID: 0023_drop_brand_kit
+Revises: 0022_report_template_cache
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0023_drop_brand_kit"
+down_revision = "0022_report_template_cache"
+branch_labels = None
+depends_on = None
+
+
+def _has(table: str, column: str) -> bool:
+    return column in {c["name"] for c in sa.inspect(op.get_bind()).get_columns(table)}
+
+
+def upgrade() -> None:
+    for table, column in (("plans", "brand_kit"), ("workspaces", "brand_json")):
+        if _has(table, column):
+            with op.batch_alter_table(table) as batch:
+                batch.drop_column(column)
+
+
+def downgrade() -> None:
+    if not _has("plans", "brand_kit"):
+        op.add_column("plans", sa.Column("brand_kit", sa.Boolean(), nullable=False, server_default=sa.false()))
+    if not _has("workspaces", "brand_json"):
+        op.add_column("workspaces", sa.Column("brand_json", sa.JSON(), nullable=True))

backend/alembic/versions/0024_plan_limits.py

@@ -0,0 +1,49 @@
+"""plan_limits: posts indexed across every source, Free allowances that are totals, new Writer and Studio numbers
+
+Revision ID: 0024_plan_limits
+Revises: 0023_drop_brand_kit
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0024_plan_limits"
+down_revision = "0023_drop_brand_kit"
+branch_labels = None
+depends_on = None
+
+PLANS = {
+    "free": dict(sources=-1, indexed_posts=5, audio_minutes=-1, audio_overviews=1, videos=2, launch_kits=2, reports=2,
+                 infographics=2, videos_monthly=False, features=[
+                     "Up to 5 posts indexed, from any source", "Grounded research chat with citations",
+                     "1 audio overview, any length", "2 videos", "2 Launch Kits", "2 infographics", "2 reports a month"]),
+    "writer": dict(sources=-1, indexed_posts=100, audio_minutes=60, audio_overviews=-1, videos=10, launch_kits=20,
+                   reports=30, infographics=30, features=[
+                       "Up to 100 posts indexed, from any source", "60 min of audio overviews a month", "10 videos a month",
+                       "20 Launch Kits a month", "30 reports a month", "30 infographics a month",
+                       "Voice cloning with consent"]),
+    "studio": dict(sources=-1, indexed_posts=250, audio_minutes=240, audio_overviews=-1, videos=20, launch_kits=50,
+                   reports=-1, infographics=-1, features=[
+                       "Up to 250 posts indexed, from any source", "240 min of audio overviews a month",
+                       "20 videos a month", "50 Launch Kits a month", "Unlimited reports", "Unlimited infographics",
+                       "Launchpad calendar and resurfacing", "Priority rendering"]),
+}
+
+
+def upgrade() -> None:
+    columns = {c["name"] for c in sa.inspect(op.get_bind()).get_columns("plans")}
+    if "audio_overviews" not in columns:
+        op.add_column("plans", sa.Column("audio_overviews", sa.Integer(), nullable=False, server_default="-1"))
+    plans = sa.table("plans", sa.column("id", sa.String), sa.column("sources", sa.Integer),
+                     sa.column("indexed_posts", sa.Integer), sa.column("audio_minutes", sa.Integer),
+                     sa.column("audio_overviews", sa.Integer), sa.column("videos", sa.Integer),
+                     sa.column("launch_kits", sa.Integer), sa.column("reports", sa.Integer),
+                     sa.column("infographics", sa.Integer), sa.column("videos_monthly", sa.Boolean),
+                     sa.column("features", sa.JSON))
+    for plan_id, values in PLANS.items():
+        op.execute(plans.update().where(plans.c.id == plan_id).values(**values))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("plans") as batch:
+        batch.drop_column("audio_overviews")

backend/alembic/versions/0025_drop_video_premium.py

@@ -0,0 +1,24 @@
+"""drop_video_premium: the premium video options are gone, so is the plan flag for them
+
+Revision ID: 0025_drop_video_premium
+Revises: 0024_plan_limits
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0025_drop_video_premium"
+down_revision = "0024_plan_limits"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    if "video_premium" in {c["name"] for c in sa.inspect(op.get_bind()).get_columns("plans")}:
+        with op.batch_alter_table("plans") as batch:
+            batch.drop_column("video_premium")
+
+
+def downgrade() -> None:
+    if "video_premium" not in {c["name"] for c in sa.inspect(op.get_bind()).get_columns("plans")}:
+        op.add_column("plans", sa.Column("video_premium", sa.Boolean(), nullable=False, server_default=sa.false()))

backend/alembic/versions/0026_plan_copy.py

@@ -0,0 +1,40 @@
+"""plan_copy: Free gets 1 video; Writer and Studio audio copy is relative to Free
+
+Revision ID: 0026_plan_copy
+Revises: 0025_drop_video_premium
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0026_plan_copy"
+down_revision = "0025_drop_video_premium"
+branch_labels = None
+depends_on = None
+
+SWAPS = {
+    "free": {"2 videos": "1 video"},
+    "writer": {"60 min of audio overviews a month": "10x more audio overviews than Free (60 min a month)"},
+    "studio": {"240 min of audio overviews a month": "40x more audio overviews than Free (240 min a month)"},
+}
+
+
+def _swap(rows: dict) -> None:
+    plans = sa.table("plans", sa.column("id", sa.String), sa.column("videos", sa.Integer), sa.column("features", sa.JSON))
+    bind = op.get_bind()
+    for plan_id, swaps in rows.items():
+        features = bind.execute(sa.select(plans.c.features).where(plans.c.id == plan_id)).scalar()
+        if features is None:
+            continue
+        values = {"features": [swaps.get(f, f) for f in features]}
+        if plan_id == "free":
+            values["videos"] = 1 if "1 video" in swaps.values() else 2
+        op.execute(plans.update().where(plans.c.id == plan_id).values(**values))
+
+
+def upgrade() -> None:
+    _swap(SWAPS)
+
+
+def downgrade() -> None:
+    _swap({k: {v: o for o, v in d.items()} for k, d in SWAPS.items()})

backend/alembic/versions/0027_quiz_attempts.py

@@ -0,0 +1,38 @@
+"""quiz_attempts: a person's last finished run of a quiz, shown again when they reopen it
+
+Revision ID: 0027_quiz_attempts
+Revises: 0026_plan_copy
+Create Date: 2026-10-08
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0027_quiz_attempts"
+down_revision = "0026_plan_copy"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 0001 builds from the live models, so a fresh database may already have the table.
+    if "quiz_attempts" in sa.inspect(op.get_bind()).get_table_names():
+        return
+    op.create_table(
+        "quiz_attempts",
+        sa.Column("id", sa.Uuid(), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("workspace_id", sa.Uuid(), sa.ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("artifact_id", sa.Uuid(), sa.ForeignKey("artifacts.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("user_id", sa.Uuid(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("score", sa.Integer(), nullable=False),
+        sa.Column("total", sa.Integer(), nullable=False),
+        sa.Column("answers", sa.JSON(), nullable=False),
+        sa.UniqueConstraint("artifact_id", "user_id"),
+    )
+    op.create_index("ix_quiz_attempts_workspace_id", "quiz_attempts", ["workspace_id"])
+    op.create_index("ix_quiz_attempts_artifact_id", "quiz_attempts", ["artifact_id"])
+
+
+def downgrade() -> None:
+    op.drop_table("quiz_attempts")

backend/app/infographics/design.py

@@ -0,0 +1,213 @@
+"""The AI-composed infographic: a page frame of ours (head, takeaway, background, mark) around a body the model writes in
+HTML from a small vocabulary of components (flow charts, timelines, hierarchies, comparisons, cards, numbers). The
+model's markup is never trusted: it is parsed and rebuilt from an allowlist of tags and class names, with no
+attributes but `class`, so it can carry no script, style, link, image or address."""
+
+import hashlib
+import random
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from bs4 import BeautifulSoup, Comment, NavigableString, Tag
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+from markupsafe import Markup
+
+from app.infographics.render import LOGO_SVG, SIZES
+
+_DIR = Path(__file__).parent / "templates"
+CSS = (_DIR / "design.css").read_text(encoding="utf-8")
+
+
+@dataclass(frozen=True)
+class Look:
+    id: str
+    name: str
+    blurb: str
+    vars: dict  # CSS variables of the palette
+
+
+LOOKS: dict[str, Look] = {l.id: l for l in (
+    Look("midnight", "Midnight", "Black and blue, white type", {
+        "bg": "#03050a", "bg2": "#0b1a3a", "ink": "#ffffff", "mute": "#9fb0cc", "acc": "#2f7bff", "acc2": "#8db8ff",
+        "line": "rgba(130,170,255,.26)", "card": "rgba(255,255,255,.04)", "hl": "rgba(47,123,255,.18)", "paper": "#ffffff",
+        "paperink": "#03050a", "star": "#ffffff", "markbg": "rgba(3,5,10,.75)", "markline": "rgba(141,184,255,.4)", "markink": "#ffffff"}),
+    Look("paper", "Orbit", "White, black type, blue orbits and stars", {
+        "bg": "#ffffff", "bg2": "#eaf1ff", "ink": "#05070d", "mute": "#4b5668", "acc": "#1f5fe6", "acc2": "#1f5fe6",
+        "line": "rgba(5,7,13,.18)", "card": "#ffffff", "hl": "rgba(31,95,230,.09)", "paper": "#05070d",
+        "paperink": "#ffffff", "star": "#1f5fe6", "markbg": "#05070d", "markline": "#05070d", "markink": "#ffffff"}),
+)}
+DEFAULT_LOOK = "midnight"
+
+# What the person can ask the layout to lean towards; "auto" lets the AI choose from the content.
+STYLES = {
+    "auto": "Choose the layout that suits the content",
+    "flowchart": "A flow chart: boxes joined by arrows, steps in order",
+    "timeline": "A timeline: what happened or happens, in order",
+    "compare": "A comparison: two sides set against each other",
+    "hierarchy": "A hierarchy: one idea and the parts it breaks into",
+    "overview": "An overview: cards of the key ideas and the numbers that matter",
+}
+
+# Every class the model's markup may use (the components in design.css); anything else is dropped.
+ALLOWED_CLASSES = {
+    "sec", "sec-t", "lead", "mono", "small", "hl", "node", "n-no", "n-t", "n-d", "flow", "col", "grid", "c2", "c3", "c4",
+    "card", "c-k", "c-t", "c-d", "timeline", "t-item", "t-when", "t-t", "t-d", "tree", "t-root", "t-kids", "compare",
+    "side", "s-h", "stats", "stat", "s-n", "s-l", "cols", "pills", "pill", "callout",
+}
+ALLOWED_TAGS = {"div", "section", "span", "p", "ul", "ol", "li", "strong", "b", "em", "i", "small", "br", "h3", "h4"}
+DROP_WITH_CONTENT = {"script", "style", "iframe", "object", "embed", "link", "meta", "svg", "img", "video", "audio", "form",
+                     "input", "button", "textarea", "select", "canvas", "math", "head", "title", "noscript", "template"}
+MAX_BODY_CHARS = 14_000
+MAX_ELEMENTS = 320
+
+_SPACE = re.compile(r"\s+")
+
+
+def _clean_text(text: str) -> str:
+    return text.replace("—", ",").replace("–", "-")
+
+
+def sanitize_body(raw: object) -> str | None:
+    """The model's body markup rebuilt from the allowlist, or None when nothing readable is left."""
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    soup = BeautifulSoup(raw[: MAX_BODY_CHARS * 2], "html.parser")
+    for c in soup.find_all(string=lambda t: isinstance(t, Comment)):
+        c.extract()
+    for tag in soup.find_all(DROP_WITH_CONTENT):
+        tag.decompose()
+    count = 0
+    for tag in list(soup.find_all(True)):
+        count += 1
+        if tag.name not in ALLOWED_TAGS or count > MAX_ELEMENTS:
+            tag.unwrap() if count <= MAX_ELEMENTS else tag.decompose()
+            continue
+        classes = [c for c in (tag.get("class") or []) if c in ALLOWED_CLASSES]
+        tag.attrs = {"class": classes} if classes else {}
+    for node in soup.find_all(string=True):
+        if isinstance(node, NavigableString):
+            node.replace_with(NavigableString(_clean_text(str(node))))
+    html = _SPACE.sub(" ", str(soup)).strip()
+    text = soup.get_text(strip=True)
+    if len(html) > MAX_BODY_CHARS or len(text) < 40:
+        return None
+    return html
+
+
+def _clip(text: object, limit: int) -> str:
+    s = _SPACE.sub(" ", re.sub(r"<[^>]*>", " ", str(text or ""))).strip()
+    s = _clean_text(s)
+    if len(s) <= limit:
+        return s
+    cut = s[: limit - 1].rsplit(" ", 1)[0].rstrip(" ,;:.-") or s[: limit - 1]
+    return cut + "…"
+
+
+def build_content(raw: dict) -> dict | None:
+    """The stored content for a model answer (title, subtitle, eyebrow, key_figures, body_html, rule, notes), or None when it is
+    too thin to draw."""
+    if hasattr(raw, "model_dump"):
+        raw = raw.model_dump()
+    title = _clip(raw.get("title"), 70)
+    body = sanitize_body(raw.get("body_html"))
+    if not title or not body:
+        return None
+    figures = []
+    for f in raw.get("key_figures") or []:
+        f = f if isinstance(f, dict) else getattr(f, "__dict__", {})
+        value, label = _clip(f.get("value"), 14), _clip(f.get("label"), 44)
+        if value and label:
+            figures.append({"value": value, "label": label})
+    notes = [n for n in (_clip(n, 100) for n in raw.get("notes") or []) if n][:3]
+    return {"title": title, "subtitle": _clip(raw.get("subtitle"), 130), "eyebrow": _clip(raw.get("eyebrow"), 30) or "Key ideas",
+            "key_figures": figures[:3], "body_html": body, "rule": _clip(raw.get("rule"), 90), "notes": notes}
+
+
+def _stars(seed: str, w: int, h: int, n: int = 90) -> str:
+    rnd = random.Random(int(hashlib.sha1(seed.encode()).hexdigest()[:8], 16))
+    out = []
+    for _ in range(n):
+        r = rnd.choice((1.2, 1.5, 1.5, 2, 2.6))
+        out.append(f'<circle cx="{rnd.randint(0, w)}" cy="{rnd.randint(0, h)}" r="{r}" fill="var(--star)" opacity="{round(rnd.uniform(.12, .5), 2)}"/>')
+    return "".join(out)
+
+
+def _orbits(w: int, h: int) -> str:
+    """The Orbit look's scenery: a ringed planet like the app's icon, orbit rings with small moons, and shooting stars."""
+    big = round(w * 0.2)
+    cx, cy = round(w * 0.86), round(h * 0.085)
+    pr = round(w * 0.05)
+
+    def ring(x, y, rx, ry, op, dash=""):
+        return (f'<ellipse cx="{x}" cy="{y}" rx="{rx}" ry="{ry}" transform="rotate(-20 {x} {y})" fill="none" stroke="var(--acc)" '
+                f'stroke-width="2" opacity="{op}"{dash}/>')
+
+    def planet_ring(front: bool):
+        sweep = 0 if front else 1
+        return (f'<g transform="rotate(-22 {cx} {cy})"><path d="M{cx - pr * 2} {cy} A{pr * 2} {round(pr * .6)} 0 0 {sweep} {cx + pr * 2} {cy}" '
+                f'fill="none" stroke="var(--acc)" stroke-width="5" opacity="{1 if front else .5}"/></g>')
+
+    out = [
+        '<defs><linearGradient id="shoot" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="var(--acc)" stop-opacity="0"/>'
+        '<stop offset="1" stop-color="var(--acc)" stop-opacity=".85"/></linearGradient></defs>',
+        ring(cx, cy, big, round(big * .3), .35, ' stroke-dasharray="3 12"'),
+        ring(cx, cy, round(big * 1.55), round(big * .46), .22),
+        ring(round(w * .06), round(h * .96), round(w * .5), round(w * .14), .2, ' stroke-dasharray="3 12"'),
+        ring(round(w * .06), round(h * .96), round(w * .34), round(w * .09), .28),
+        planet_ring(False),
+        f'<circle cx="{cx}" cy="{cy}" r="{pr}" fill="var(--bg)" stroke="var(--acc)" stroke-width="5"/>',
+        f'<circle cx="{cx}" cy="{cy}" r="{pr - 12}" fill="var(--acc)" opacity=".12"/>',
+        planet_ring(True),
+        f'<circle cx="{round(w * .6)}" cy="{round(h * .036)}" r="9" fill="var(--acc)" opacity=".7"/>',
+        f'<circle cx="{round(w * .31)}" cy="{round(h * .93)}" r="8" fill="var(--acc)" opacity=".6"/>',
+    ]
+    for fx, fy, length, op in ((.46, .2, 190, .8), (.7, .4, 150, .6), (.12, .55, 120, .5)):
+        x, y = round(w * fx), round(h * fy)
+        out.append(f'<g transform="rotate(28 {x} {y})" opacity="{op}"><rect x="{x - length}" y="{y - 2}" width="{length}" height="4" rx="2" fill="url(#shoot)"/>'
+                   f'<circle cx="{x}" cy="{y}" r="5" fill="var(--acc)"/></g>')
+    return "".join(out)
+
+
+_ENV = Environment(loader=FileSystemLoader(_DIR), autoescape=select_autoescape(["j2", "html"], default=True), undefined=StrictUndefined,
+                   trim_blocks=True, lstrip_blocks=True)
+
+
+def render_design(look: str, content: dict, layout: str = "portrait", fit: float | None = None) -> str:
+    """The page for an AI-composed infographic. `fit` is the scale that makes its body fit (stored with the content)."""
+    look = look if look in LOOKS else DEFAULT_LOOK
+    layout = layout if layout in SIZES else "portrait"
+    w, h = SIZES[layout]
+    if fit is None:
+        fit = float(((content.get("fit") or {}) if isinstance(content.get("fit"), dict) else {}).get(layout) or 1)
+    fit = max(0.5, min(1.0, fit))
+    vars_css = ";".join(f"--{k}:{v}" for k, v in LOOKS[look].vars.items())
+    return _ENV.get_template("design.html.j2").render(
+        c=content, look=look, layout=layout, w=w, h=h, fit=fit, vars_css=vars_css, css=Markup(CSS), logo=Markup(LOGO_SVG),
+        body=Markup(content["body_html"]),
+        stars=Markup(_stars(content["title"] + look, w, h) + (_orbits(w, h) if look == "paper" else "")),
+        fonts="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@300;400;500;600&family=JetBrains+Mono:wght@400;500;700&display=swap")
+
+
+SAMPLE_BODY = (
+    '<section class="sec"><div class="sec-t">The five layers</div><div class="flow">'
+    '<div class="node"><span class="n-no">01</span><span class="n-t">Prompt</span><span class="n-d">Wording, examples and format of one request.</span></div>'
+    '<div class="node"><span class="n-no">02</span><span class="n-t">Context</span><span class="n-d">Docs, history, tools and memory for each call.</span></div>'
+    '<div class="node hl"><span class="n-no">03</span><span class="n-t">Harness</span><span class="n-d">Tools, checks and guardrails around the model.</span></div>'
+    '<div class="node"><span class="n-no">04</span><span class="n-t">Loop</span><span class="n-d">Reason, act and observe until done.</span></div></div></section>'
+    '<section class="sec"><div class="sec-t">Every request goes through</div><div class="grid c4">'
+    + "".join(f'<div class="card{" hl" if i == 3 else ""}"><span class="c-k">Step {i + 1}</span><span class="c-t">{t}</span><span class="c-d">{d}</span></div>'
+              for i, (t, d) in enumerate([("Auth", "Identity, limits and input guards."), ("Cache", "Answers to repeat questions."),
+                                          ("Safety", "Scrub PII, catch injection."), ("Memory", "Session history, summarised."),
+                                          ("Retrieve", "Fetch docs, split queries."), ("Answer", "Sub-queries in parallel."),
+                                          ("Validate", "Check quality first."), ("Save", "Store and log one trace.")]))
+    + '</div></section>'
+    '<section class="sec"><div class="sec-t">Why it matters</div><div class="callout">Each layer builds on the one below it, so start at the bottom and add a layer only when the task needs it.</div></section>'
+)
+SAMPLE = {"title": "From Prompt to Production Agent", "subtitle": "Five engineering layers and the steps every request takes",
+          "eyebrow": "Agent engineering", "body_html": SAMPLE_BODY,
+          "key_figures": [{"value": "5", "label": "engineering layers"}, {"value": "8", "label": "steps on every request"},
+                          {"value": "30%", "label": "of traffic skips the pipeline"}],
+          "rule": "Most tasks only need the bottom layers; avoid complex graphs without cause.",
+          "notes": ["Each layer builds on the one below it.", "Cache and middleware run outside the graph.",
+                    "Every request produces one end-to-end trace."]}

backend/app/infographics/templates/design.css

@@ -0,0 +1,126 @@
+/* The infographic design system: black, blue and white, thin lines, flow charts. The page frame (head, takeaway, mark, the
+   background) is ours; the body is composed by the AI from the components below, and only these class names survive the
+   sanitiser (design.ALLOWED_CLASSES). */
+.ig2,.ig2 *{box-sizing:border-box;margin:0;padding:0}
+.ig2{position:relative;width:var(--w);height:var(--h);overflow:hidden;color:var(--ink);font-family:'Inter',sans-serif;
+  background:radial-gradient(1300px 900px at 82% 6%,var(--bg2),var(--bg) 68%)}
+.ig2 .ig-bg{position:absolute;inset:0;pointer-events:none}
+.ig2 .ig-main{position:absolute;left:110px;right:110px;top:84px;bottom:132px;display:flex;flex-direction:column;gap:34px}
+.ig2 .ig-left{display:contents}
+.ig2 .ig-head{order:1;position:relative;flex:none;min-height:286px}
+.ig2 .ig-body{order:2;flex:1;min-height:0;overflow:hidden;display:flex}
+.ig2 .ig-take{order:3;flex:none}
+
+.ig2 .ig-eyebrow{display:flex;align-items:center;gap:16px;font:500 20px 'JetBrains Mono',monospace;letter-spacing:.24em;text-transform:uppercase;color:var(--acc2);margin-bottom:20px}
+.ig2 .ig-eyebrow:before{content:"";width:44px;height:2px;background:var(--acc)}
+.ig2 h1{font:600 74px/1.04 'Space Grotesk',sans-serif;letter-spacing:-.02em;max-width:850px;margin-bottom:20px}
+.ig2 .ig-sub{font-size:30px;line-height:1.38;color:var(--mute);max-width:850px}
+/* The key figures: the few numbers or short facts that matter most, beside the title (or under it when wide) */
+.ig2 .ig-figs{position:absolute;right:0;top:0;width:430px;display:flex;flex-direction:column;gap:16px}
+.ig2 .fig{padding:6px 0 6px 24px;border-left:3px solid var(--acc)}
+.ig2 .fig-v{display:block;font:600 56px/1.02 'Space Grotesk',sans-serif;letter-spacing:-.02em;overflow-wrap:anywhere}
+.ig2 .fig-l{display:block;margin-top:6px;font:500 19px 'JetBrains Mono',monospace;letter-spacing:.1em;text-transform:uppercase;color:var(--mute)}
+
+.ig2 .ig-take{display:grid;grid-template-columns:1.05fr 1fr;gap:48px;align-items:center;padding:32px 46px;border-radius:16px;background:var(--paper);color:var(--paperink)}
+.ig2 .ig-take .q{font:600 38px/1.16 'Space Grotesk',sans-serif;letter-spacing:-.01em}
+.ig2 .ig-take ul{list-style:none;font-size:24px;line-height:1.38}
+.ig2 .ig-take li{position:relative;padding-left:28px;margin:8px 0}
+.ig2 .ig-take li:before{content:"";position:absolute;left:0;top:12px;width:11px;height:11px;border-radius:50%;background:var(--acc)}
+
+.ig2 .ig-mark{position:absolute;right:44px;bottom:34px;display:flex;align-items:center;gap:16px;padding:8px 26px 8px 10px;border-radius:999px;
+  background:var(--markbg);border:1px solid var(--markline);font:700 30px 'JetBrains Mono',monospace;letter-spacing:.04em;color:var(--markink)}
+.ig2 .ig-mark svg{width:52px;height:52px;display:block}
+
+/* The body: fitted by scaling when the AI wrote more than a poster holds (the scale is measured once, when it is made) */
+.ig2 .ig-inner{display:flex;flex-direction:column;justify-content:space-evenly;gap:34px;min-height:calc(100% / var(--fit,1));flex:none;width:calc(1380px / var(--fit,1));transform:scale(var(--fit,1));transform-origin:0 0}
+.ig2 .sec{display:flex;flex-direction:column;gap:20px}
+.ig2 .sec-t{display:flex;align-items:center;gap:18px;font:500 20px 'JetBrains Mono',monospace;letter-spacing:.22em;text-transform:uppercase;color:var(--acc2)}
+.ig2 .sec-t:after{content:"";flex:1;height:1.5px;background:var(--line)}
+.ig2 .lead{font-size:28px;line-height:1.4;color:var(--ink)}
+.ig2 .ig-inner p{font-size:24px;line-height:1.4;color:var(--mute)}
+.ig2 .ig-inner strong,.ig2 .ig-inner b{color:var(--ink);font-weight:600}
+.ig2 .ig-inner em,.ig2 .ig-inner i{color:var(--acc2);font-style:normal}
+.ig2 .mono{font-family:'JetBrains Mono',monospace}
+.ig2 .small{font-size:20px}
+
+/* A box in a flow: a small number, a title, a line of text */
+.ig2 .node{position:relative;padding:24px 26px;border:1.5px solid var(--line);border-radius:14px;background:linear-gradient(var(--card),var(--card)),linear-gradient(var(--bg),var(--bg))}
+.ig2 .node.hl{background:linear-gradient(var(--hl),var(--hl)),linear-gradient(var(--bg),var(--bg));border-color:var(--acc)}
+.ig2 .n-no{display:block;font:500 19px 'JetBrains Mono',monospace;letter-spacing:.14em;color:var(--acc2);margin-bottom:10px}
+.ig2 .n-t{display:block;font:600 31px/1.15 'Space Grotesk',sans-serif;margin-bottom:8px}
+.ig2 .n-d{display:block;font-size:23px;line-height:1.38;color:var(--mute)}
+
+/* Flow chart: boxes in a row (or a column) joined by arrows */
+.ig2 .flow{display:flex;gap:58px;align-items:stretch}
+.ig2 .flow>.node{flex:1;min-width:0}
+.ig2 .flow>.node+.node:before{content:"";position:absolute;left:-48px;top:50%;width:34px;height:2px;background:var(--acc)}
+.ig2 .flow>.node+.node:after{content:"";position:absolute;left:-15px;top:50%;margin-top:-7px;border-style:solid;border-width:7px 0 7px 11px;border-color:transparent transparent transparent var(--acc)}
+.ig2 .flow.col{flex-direction:column;gap:50px}
+.ig2 .flow.col>.node+.node:before{left:50%;top:-40px;width:2px;height:28px;margin-left:-1px}
+.ig2 .flow.col>.node+.node:after{left:50%;top:-13px;margin:0 0 0 -7px;border-width:11px 7px 0 7px;border-color:var(--acc) transparent transparent transparent}
+
+/* Cards in a grid */
+.ig2 .grid{display:grid;gap:22px}
+.ig2 .c2{grid-template-columns:repeat(2,minmax(0,1fr))}
+.ig2 .c3{grid-template-columns:repeat(3,minmax(0,1fr))}
+.ig2 .c4{grid-template-columns:repeat(4,minmax(0,1fr))}
+.ig2 .card{padding:24px 26px 26px;border:1.5px solid var(--line);border-top:3px solid var(--acc);border-radius:14px;background:linear-gradient(var(--card),var(--card)),linear-gradient(var(--bg),var(--bg))}
+.ig2 .card.hl{background:linear-gradient(var(--hl),var(--hl)),linear-gradient(var(--bg),var(--bg));border-color:var(--acc)}
+.ig2 .c-k{display:block;font:500 19px 'JetBrains Mono',monospace;letter-spacing:.14em;text-transform:uppercase;color:var(--acc2);margin-bottom:10px}
+.ig2 .c-t{display:block;font:600 29px/1.15 'Space Grotesk',sans-serif;margin-bottom:8px}
+.ig2 .c-d{display:block;font-size:22px;line-height:1.38;color:var(--mute)}
+
+/* A timeline: a line with a dot for each moment */
+.ig2 .timeline{position:relative;display:flex;flex-direction:column;gap:28px;padding-left:46px}
+.ig2 .timeline:before{content:"";position:absolute;left:10px;top:8px;bottom:8px;width:2px;background:var(--line)}
+.ig2 .t-item{position:relative}
+.ig2 .t-item:before{content:"";position:absolute;left:-46px;top:6px;width:16px;height:16px;border-radius:50%;background:var(--bg);border:3px solid var(--acc)}
+.ig2 .t-when{display:block;font:500 19px 'JetBrains Mono',monospace;letter-spacing:.14em;text-transform:uppercase;color:var(--acc2);margin-bottom:6px}
+.ig2 .t-t{display:block;font:600 30px/1.15 'Space Grotesk',sans-serif;margin-bottom:6px}
+.ig2 .t-d{display:block;font-size:23px;line-height:1.38;color:var(--mute)}
+
+/* A hierarchy: one box over the boxes it leads to, joined by lines */
+.ig2 .tree{display:flex;flex-direction:column;align-items:center}
+.ig2 .t-root{width:560px;max-width:100%;text-align:center;position:relative}
+.ig2 .t-root:after{content:"";position:absolute;left:50%;top:100%;width:2px;height:28px;margin-left:-1px;background:var(--acc)}
+.ig2 .t-kids{display:flex;gap:24px;width:100%;margin-top:28px}
+.ig2 .t-kids>*{flex:1;min-width:0;position:relative;margin-top:28px}
+.ig2 .t-kids>*:before{content:"";position:absolute;left:50%;top:-28px;width:2px;height:28px;margin-left:-1px;background:var(--acc)}
+.ig2 .t-kids>*:after{content:"";position:absolute;top:-28px;left:-12px;right:-12px;height:2px;background:var(--acc)}
+.ig2 .t-kids>*:first-child:after{left:50%}
+.ig2 .t-kids>*:last-child:after{right:50%}
+.ig2 .t-kids>*:only-child:after{display:none}
+
+/* Two sides compared */
+.ig2 .compare{display:grid;grid-template-columns:1fr 1fr;border:1.5px solid var(--line);border-radius:14px;overflow:hidden}
+.ig2 .side{padding:26px 32px 22px;background:linear-gradient(var(--card),var(--card)),linear-gradient(var(--bg),var(--bg))}
+.ig2 .side+.side{border-left:1.5px solid var(--line)}
+.ig2 .side.hl{background:linear-gradient(var(--hl),var(--hl)),linear-gradient(var(--bg),var(--bg))}
+.ig2 .s-h{display:block;font:600 32px/1.15 'Space Grotesk',sans-serif;margin-bottom:14px}
+.ig2 .side ul{list-style:none}
+.ig2 .side li{position:relative;padding:13px 0 13px 30px;border-top:1px solid var(--line);font-size:23px;line-height:1.35;color:var(--mute)}
+.ig2 .side li:before{content:"";position:absolute;left:2px;top:23px;width:10px;height:10px;border-radius:50%;background:var(--acc)}
+
+/* Big numbers */
+.ig2 .stats{display:grid;grid-auto-flow:column;grid-auto-columns:minmax(0,1fr);gap:22px}
+.ig2 .stat{padding:20px 26px 22px;border-left:3px solid var(--acc);background:linear-gradient(var(--card),var(--card)),linear-gradient(var(--bg),var(--bg));border-radius:0 12px 12px 0}
+.ig2 .s-n{display:block;font:600 62px/1 'Space Grotesk',sans-serif;letter-spacing:-.02em}
+.ig2 .s-l{display:block;font-size:22px;line-height:1.35;color:var(--mute);margin-top:8px}
+
+.ig2 .cols{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:40px}
+.ig2 .pills{display:flex;flex-wrap:wrap;gap:12px}
+.ig2 .pill{padding:10px 22px;border:1.5px solid var(--line);border-radius:999px;font-size:22px;background:linear-gradient(var(--card),var(--card)),linear-gradient(var(--bg),var(--bg))}
+.ig2 .callout{padding:24px 30px;border-left:4px solid var(--acc);background:linear-gradient(var(--hl),var(--hl)),linear-gradient(var(--bg),var(--bg));border-radius:0 12px 12px 0;font-size:27px;line-height:1.38}
+
+/* Wide: the title and the takeaway in a column, the body beside them */
+.ig2.landscape .ig-main{top:70px;bottom:104px;flex-direction:row;gap:60px}
+.ig2.landscape .ig-left{display:flex;flex-direction:column;justify-content:space-between;gap:28px;width:600px;flex:none;min-height:0}
+.ig2.landscape .ig-head{min-height:0}
+.ig2.landscape h1{font-size:58px;max-width:none}
+.ig2.landscape .ig-sub{font-size:27px;max-width:none}
+.ig2.landscape .ig-figs{position:static;width:100%;margin-top:34px;gap:14px}
+.ig2.landscape .fig-v{font-size:50px}
+.ig2.landscape .ig-body{order:0;width:1380px;flex:none}
+.ig2.landscape .ig-take{grid-template-columns:1fr;gap:18px;padding:30px 34px}
+.ig2.landscape .ig-take .q{font-size:35px}
+.ig2.landscape .ig-take ul{font-size:22px}

backend/app/infographics/templates/design.html.j2

@@ -0,0 +1,22 @@
+{#- The frame of an AI-composed infographic. `body` is sanitised markup (design.sanitize_body); every other value is autoescaped. -#}
+<link rel="stylesheet" href="{{ fonts }}">
+<style>{{ css }}</style>
+<div class="ig2 look-{{ look }} {{ layout }}" style="--w:{{ w }}px;--h:{{ h }}px;--fit:{{ fit }};{{ vars_css }}">
+  <svg class="ig-bg" width="{{ w }}" height="{{ h }}" viewBox="0 0 {{ w }} {{ h }}">{{ stars }}</svg>
+  <div class="ig-main">
+    <div class="ig-left">
+      <header class="ig-head">
+        <div class="ig-eyebrow">{{ c.eyebrow }}</div>
+        <h1>{{ c.title }}</h1>
+        <p class="ig-sub">{{ c.subtitle }}</p>
+        {% if c.key_figures %}<div class="ig-figs">{% for f in c.key_figures %}<div class="fig"><span class="fig-v">{{ f.value }}</span><span class="fig-l">{{ f.label }}</span></div>{% endfor %}</div>{% endif %}
+      </header>
+      <div class="ig-take">
+        <div class="q">{{ c.rule }}</div>
+        <ul>{% for n in c.notes %}<li>{{ n }}</li>{% endfor %}</ul>
+      </div>
+    </div>
+    <div class="ig-body"><div class="ig-inner">{{ body }}</div></div>
+  </div>
+  <div class="ig-mark">{{ logo }}<span>notestack.ai</span></div>
+</div>

backend/app/pipeline/idea_pool.py

@@ -0,0 +1,85 @@
+"""Flashcards (always) and quizzes (above ARTIFACT_MAX_POSTS posts) from the ideas already extracted from each post, the same stored
+ideas the Mind Constellation is drawn from. Instead of sending post text, a small random sample of those ideas goes to the model: each
+as one line with the post and the lines it came from, so the model can cite them and the existing check can verify the lines.
+Nothing here extracts anything and no post text is read: a post with no stored ideas yet is represented by a short opening, at most
+a few of them. A sample of ARTIFACT_IDEA_SAMPLE ideas is about 1,500 tokens whatever the size of the selection."""
+
+import math
+import random
+import re
+import uuid
+
+from sqlalchemy.orm import Session
+
+from app.config import settings
+from app.corpus import Corpus
+from app.models import Document
+from app.pipeline.generate import ideas_fresh
+from app.pipeline.passages import passages_for
+
+IDEAS_PER_POST = 2  # so a few posts cannot fill the sample (more when the selection is small, to fill it)
+OPENING_BUDGET = 800  # characters of a post's opening, for a post with no stored ideas
+MAX_OPENINGS = 3  # posts with no stored ideas represented by their opening
+CHAT_BUDGET = 12_000  # characters of chat transcripts kept (the end of each) when chats are picked as well
+
+FORMAT_NOTE = ("Each item below is a key idea from one post, written as: IDEA [path lines a-b] label: note. The path and lines say "
+               "where in the post the idea comes from. When a question or card comes from an idea, cite that path and those lines.")
+
+_STOP = {"the", "and", "for", "with", "that", "this", "from", "how", "what", "why", "are", "was", "about", "your", "you",
+         "into", "over", "does", "can", "not", "but", "all", "any", "its", "their", "them", "will", "have", "has"}
+
+
+def _tokens(text: str) -> set[str]:
+    return {w for w in re.findall(r"[a-z0-9]{3,}", (text or "").lower()) if w not in _STOP}
+
+
+def has_ideas(docs: list[Document]) -> int:
+    """How many of the posts have their ideas stored and current."""
+    return sum(1 for d in docs if ideas_fresh(d))
+
+
+def _line(doc: Document, idea: dict) -> str:
+    """One stored idea as one line, tagged with where it came from (its first cited range, when it has one)."""
+    where = doc.path
+    for ref in idea.get("sources") or []:
+        try:
+            a, b = int(ref["line_start"]), int(ref["line_end"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        where = f"{doc.path} lines {a}-{max(a, b)}"
+        break
+    label, note = (idea.get("label") or "").strip(), (idea.get("note") or "").strip()
+    return f"IDEA [{where}] {label}: {note}"
+
+
+def sample(db: Session, workspace_id: uuid.UUID, docs: list[Document], topic: str = "", chats: list[str] | None = None,
+           size: int | None = None, rng: random.Random | None = None) -> list[str]:
+    """The material for one call: the format note, a random sample of the posts' stored ideas, a few short openings for posts with
+    none, and the end of any chats. With a topic, ideas that match it come first. A fresh draw each time unless `rng` is given."""
+    rng = rng or random.Random()
+    size = size or max(settings.artifact_idea_sample, 1)
+    wanted = _tokens(topic)
+    have = [d for d in docs if ideas_fresh(d)]
+    per_post = max(IDEAS_PER_POST, math.ceil(size / max(len(have), 1)))
+    matching: list[tuple[Document, dict]] = []
+    rest: list[tuple[Document, dict]] = []
+    for d in have:
+        mine = [i for i in (d.metadata_json or {}).get("ideas") or [] if (i.get("label") or "").strip()]
+        rng.shuffle(mine)
+        for idea in mine[:per_post]:
+            hit = wanted and wanted & _tokens(" ".join([idea.get("label", ""), idea.get("note", ""), d.title]))
+            (matching if hit else rest).append((d, idea))
+    rng.shuffle(matching)
+    rng.shuffle(rest)
+    chosen = (matching + rest)[:size]
+    rng.shuffle(chosen)  # not grouped by relevance or by post
+    out = [FORMAT_NOTE] + [_line(d, i) for d, i in chosen]
+    bare = [d for d in docs if not ideas_fresh(d)]
+    if bare:
+        corpus = Corpus(workspace_id)
+        for d in rng.sample(bare, min(MAX_OPENINGS, len(bare))):
+            out.extend(passages_for(corpus, [d], budget_chars=OPENING_BUDGET))
+    if chats:
+        share = CHAT_BUDGET // len(chats)
+        out += [t[-share:] for t in chats]
+    return out

backend/app/pipeline/report_blueprint.py

@@ -0,0 +1,220 @@
+"""The plan of a themed report, made before any of it is written.
+
+One model call (PlanReportBlueprint) sees the themes with their weights and the reader's request, never the posts, and plans the
+whole report: a storyline, the sections in order (what each is about, how deep, what it must cover), and which section bridges which
+themes. Code then checks the plan against the weights, because a plan that forgets a major theme or gives a footnote the room of a
+main theme is wrong however well it reads: every major or asked-for theme gets a section, depth follows the theme's tier, a body
+theme belongs to one section, and what other sections own is worked out here, not left to the model."""
+
+import logging
+import time
+import uuid
+from dataclasses import dataclass, field
+
+from sqlalchemy.orm import Session
+
+from app.llm import run
+from app.llm.provider import report_plan_lm
+from app.llm.signatures import PlanReportBlueprint
+from app.models import Job
+from app.pipeline.report_themes import Theme
+
+log = logging.getLogger(__name__)
+
+MAX_SECTIONS = 8
+MAX_CONNECTIONS = 6
+ROLES = ("intro", "body", "synthesis", "summary")
+MORE_HEADING = "More to know"  # where the themes no section took are gathered
+
+
+class BlueprintUnavailable(Exception):
+    """The plan was not usable: the caller reads the posts as before."""
+
+
+@dataclass
+class Section:
+    heading: str
+    role: str
+    brief: str
+    theme_ids: list[str]
+    depth: str = "standard"
+    must_cover: list[str] = field(default_factory=list)
+    embed: dict | None = None
+    covered_elsewhere: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Blueprint:
+    title: str
+    storyline: str
+    sections: list[Section]
+    connections: list[dict]  # {"theme_ids": [...], "relation": str, "section": heading}
+
+
+def theme_lines(themes: list[Theme]) -> list[str]:
+    """The themes as the planner reads them: id | name | tier | weight | posts | asked for: summary, then a few of their ideas."""
+    return [f"{t.id} | {t.name} | {t.tier} | {t.weight:.2f} | {len(t.doc_ids)} posts | "
+            f"{'asked for' if t.pinned else 'not asked for'}: {t.summary} (e.g. {'; '.join(i.label for i in t.ideas[:3])})"
+            for t in themes]
+
+
+def relation_lines(relations: list[dict]) -> list[str]:
+    return [f"{r['a']} <-> {r['b']}: {r['relation']}" for r in relations]
+
+
+def derived_depth(section: Section, by_id: dict[str, Theme]) -> str:
+    """How deep a section goes follows its heaviest theme, whatever the model wrote: the weights are the plan's reason to exist."""
+    if section.role in ("intro", "summary"):
+        return "brief"
+    tiers = {by_id[i].tier + ("!" if by_id[i].pinned else "") for i in section.theme_ids if i in by_id}
+    if any(t.startswith("major") or t.endswith("!") for t in tiers):
+        return "deep"
+    if section.role == "synthesis" or any(t.startswith("medium") for t in tiers):
+        return "standard"
+    return "brief"
+
+
+def _first_index(sections: list[Section], role: str) -> int | None:
+    return next((n for n, s in enumerate(sections) if s.role == role), None)
+
+
+def _in_reading_order(sections: list[Section]) -> list[Section]:
+    """The intro first, the summary last, whatever order the model gave them in. One of each."""
+    intro = [s for s in sections if s.role == "intro"][:1]
+    summary = [s for s in sections if s.role == "summary"][-1:]
+    return intro + [s for s in sections if s.role in ("body", "synthesis")] + summary
+
+
+def repair(bp: Blueprint, themes: list[Theme]) -> Blueprint:
+    """Make the plan agree with the weights. Raises BlueprintUnavailable when fewer than two sections remain."""
+    by_id = {t.id: t for t in themes}
+    sections = [s for s in bp.sections if s.heading.strip()]
+    planned = len(sections)
+
+    # A body theme is the subject of one section; unknown ids go.
+    seen: set[str] = set()
+    for s in sections:
+        s.theme_ids = [i for n, i in enumerate(s.theme_ids) if i in by_id and i not in s.theme_ids[:n]]
+        if s.role == "body":
+            s.theme_ids = [i for i in s.theme_ids if i not in seen]
+            seen.update(s.theme_ids)
+    before = len(sections)
+    sections = [s for s in sections if s.role != "body" or s.theme_ids]
+    if len(sections) < before:
+        log.info("report blueprint: dropped %d body sections with no theme of their own", before - len(sections))
+    sections = _in_reading_order(sections)
+
+    def insert(section: Section) -> None:
+        at = _first_index(sections, "summary")
+        sections.insert(len(sections) if at is None else at, section)
+
+    # Every major or asked-for theme has a section; whatever else no section took is gathered into one.
+    for t in sorted(themes, key=lambda t: -t.weight):
+        if t.id not in seen and (t.tier == "major" or t.pinned):
+            log.info("report blueprint: no section for %s theme %s (%s), added one", "asked-for" if t.pinned else t.tier, t.id,
+                     t.name)
+            insert(Section(heading=t.name, role="body", brief=t.summary, theme_ids=[t.id], depth="deep"))
+            seen.add(t.id)
+    rest = [t.id for t in sorted(themes, key=lambda t: -t.weight) if t.id not in seen]
+    if rest:
+        log.info("report blueprint: themes in no section %s go to %r", rest, MORE_HEADING)
+        more = next((s for s in sections if s.role == "body" and s.heading == MORE_HEADING), None)
+        if more:
+            more.theme_ids += rest
+        else:
+            insert(Section(heading=MORE_HEADING, role="body", theme_ids=rest, depth="brief",
+                           brief="The smaller themes in the posts, in a line or two each."))
+        seen.update(rest)
+
+    # Too many sections: the lightest body sections (never one holding a major or asked-for theme) are gathered into one brief
+    # section, so a footnote never shares a section with a main theme.
+    def weight(s: Section) -> float:
+        return sum(by_id[i].weight for i in s.theme_ids)
+
+    def protected(s: Section) -> bool:
+        return any(by_id[i].tier == "major" or by_id[i].pinned for i in s.theme_ids)
+
+    while len(sections) > MAX_SECTIONS:
+        more = next((s for s in sections if s.role == "body" and s.heading == MORE_HEADING), None)
+        candidates = [s for s in sections if s.role == "body" and not protected(s) and s is not more]
+        if not candidates:
+            break
+        lightest = min(candidates, key=weight)
+        log.info("report blueprint: %d sections, over the %d allowed: merging %r (themes %s) into %r", len(sections),
+                 MAX_SECTIONS, lightest.heading, lightest.theme_ids, MORE_HEADING)
+        if more:
+            more.theme_ids += lightest.theme_ids
+            sections.remove(lightest)
+        else:
+            lightest.heading, lightest.must_cover = MORE_HEADING, []
+            lightest.brief = "The smaller themes in the posts, in a line or two each."
+
+    # intro first, summary last, depth from the weights, the summary restates the main themes.
+    sections = _in_reading_order(sections)
+    for s in [s for s in sections if s.role == "summary"]:
+        s.theme_ids = [t.id for t in themes if t.tier == "major" or t.pinned] or s.theme_ids
+    for s in sections:
+        s.depth = derived_depth(s, by_id)
+    if len(sections) < 2:
+        log.warning("report blueprint unusable: sections=%d planned=%d", len(sections), planned)
+        raise BlueprintUnavailable("the plan has fewer than two sections")
+
+    # What the other body sections own, so no section writes another's points. The intro and summary may touch everything.
+    for s in sections:
+        s.covered_elsewhere = [] if s.role in ("intro", "summary") else [
+            f"{o.heading}: {'; '.join(o.must_cover) or o.brief}"[:240] for o in sections
+            if o is not s and o.role in ("body", "synthesis")]
+
+    headings = {s.heading.lower(): s.heading for s in sections}
+    connections = []
+    for c in bp.connections:
+        ids = [i for i in c.get("theme_ids") or [] if i in by_id]
+        relation = (c.get("relation") or "").strip()
+        if len(ids) < 2 or not relation:
+            continue
+        home = headings.get(str(c.get("section", "")).strip().lower()) or next(
+            (s.heading for s in sections if s.role in ("body", "synthesis") and set(ids) & set(s.theme_ids)), None)
+        if home:
+            connections.append({"theme_ids": ids, "relation": relation[:200], "section": home})
+    log.info("report blueprint checked: planned=%d final=%d connections=%d/%d", planned, len(sections), len(connections),
+             len(bp.connections))
+    for n, s in enumerate(sections, start=1):
+        log.info("report section %d: heading=%r role=%s depth=%s themes=%s must_cover=%d embed=%s", n, s.heading, s.role, s.depth,
+                 s.theme_ids, len(s.must_cover), (s.embed or {}).get("kind"))
+    return Blueprint(title=bp.title, storyline=bp.storyline, sections=sections, connections=connections[:MAX_CONNECTIONS])
+
+
+def plan_blueprint(db: Session, job: Job | None, workspace_id: uuid.UUID, title: str, request: str,
+                   themes: list[Theme], relations: list[dict], kinds: list[str], language: str) -> Blueprint:
+    """The checked plan for these themes. Raises BlueprintUnavailable (or whatever the model call raised) when there is none."""
+    log.info("report blueprint: asking the model workspace=%s themes=%d relations=%d allowed_visuals=%s", workspace_id, len(themes),
+             len(relations), kinds)
+    started = time.monotonic()
+    out = run.predict(PlanReportBlueprint, db=db, workspace_id=workspace_id, job=job, lm=report_plan_lm(), title=title,
+                      request=request, themes=theme_lines(themes), relations=relation_lines(relations), allowed_kinds=kinds,
+                      language=language, max_sections=MAX_SECTIONS)
+    sections = []
+    for s in out.get("sections") or []:
+        heading = (s.get("heading") or "").strip()
+        if heading:
+            sections.append(Section(
+                heading=heading, role=s.get("role") if s.get("role") in ROLES else "body", brief=(s.get("brief") or "").strip(),
+                theme_ids=[str(i) for i in s.get("theme_ids") or []], depth=s.get("depth") or "standard",
+                must_cover=[str(p).strip() for p in s.get("must_cover") or [] if str(p).strip()][:4], embed=s.get("embed")))
+    log.info("report blueprint: model answered sections=%d connections=%d seconds=%.1f", len(sections),
+             len(out.get("connections") or []), time.monotonic() - started)
+    bp = Blueprint(title=(out.get("report_title") or title).strip(), storyline=(out.get("storyline") or "").strip(),
+                   sections=sections, connections=out.get("connections") or [])
+    return repair(bp, themes)
+
+
+def outline(bp: Blueprint) -> list[str]:
+    """Every section as every writer sees it: number, heading, role, what it says."""
+    return [f"{n}. {s.heading} ({s.role}): {s.brief}" for n, s in enumerate(bp.sections, start=1)]
+
+
+def connection_lines(bp: Blueprint, themes: list[Theme], heading: str | None = None) -> list[str]:
+    """The connections (all of them, or the ones one section bridges) as 'Pricing + Hiring: how they connect (section)'."""
+    names = {t.id: t.name for t in themes}
+    return [f"{' + '.join(names[i] for i in c['theme_ids'])}: {c['relation']} (bridged in: {c['section']})"
+            for c in bp.connections if heading is None or c["section"] == heading]

backend/app/pipeline/report_evidence.py

@@ -0,0 +1,166 @@
+"""The evidence a themed report section is written from. Plain code, no model.
+
+A section is about one or more themes (report_themes.py) and its depth (report_blueprint.py) says how much room it has. What
+the writer gets, from the posts that have ideas in those themes:
+
+  - the posts that say the most about them (most of the section's themes first, then most ideas) as the writer wrote them: numbered
+    lines taken from around the lines the ideas came from, with the start of the post for context; a short post that is mostly about
+    the theme goes in whole. Several posts, each with an equal share, so a section blends posts and does not walk through one;
+  - every other post in the themes as the short summaries already stored for it (label, note, points, and the lines to cite);
+  - nothing raw for a brief section: summaries only.
+
+Nothing is cited in the report, so the text carries no line numbers and no paths: a post is named by its title."""
+
+import logging
+import math
+import uuid
+from dataclasses import dataclass, field
+
+from app.corpus import Corpus
+from app.models import Document
+from app.pipeline.passages import _body_start
+from app.pipeline.report_blueprint import Section
+from app.pipeline.report_themes import Idea, Theme
+
+BUDGETS = {"deep": 32_000, "standard": 16_000, "brief": 4_000}  # characters of evidence (about 8k, 4k and 1k tokens)
+RAW_POSTS = {"deep": 5, "standard": 3, "brief": 0}  # posts read as written, at most
+RAW_SHARE = 0.75  # of the budget when other posts are summarised too
+WHOLE_POST_CHARS = 10_000  # a post this short, mostly about the theme, goes in whole (about 2,500 tokens)
+WHOLE_POST_SHARE = 0.5
+MARGIN = 6  # lines kept around the lines an idea came from
+LEAD_LINES = 6  # lines kept from the start of a post, for context
+JOIN_GAP = 2  # windows this close are one
+SUMMARY_DETAILS = 2
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Evidence:
+    blocks: list[str] = field(default_factory=list)
+    posts: list[str] = field(default_factory=list)  # paths of every post used
+    raw_posts: int = 0  # how many of them were read as written
+
+
+def _merge(ranges: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    out: list[tuple[int, int]] = []
+    for a, b in sorted(ranges):
+        if out and a <= out[-1][1] + JOIN_GAP:
+            out[-1] = (out[-1][0], max(out[-1][1], b))
+        else:
+            out.append((a, b))
+    return out
+
+
+def _text(lines: list[str], a: int, b: int) -> list[str]:
+    return [lines[n - 1] for n in range(a, min(b, len(lines)) + 1) if lines[n - 1].strip()]
+
+
+def _idea_ranges(d: Document, ideas: list[Idea], total: int, first: int) -> list[tuple[int, int]]:
+    out = []
+    for idea in ideas:
+        for s in idea.sources:
+            try:
+                a, b = int(s["line_start"]), int(s["line_end"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            if s.get("path") == d.path and total:
+                out.append((max(first + 1, a - MARGIN), min(total, max(a, b) + MARGIN)))
+    return out
+
+
+def raw_post(corpus: Corpus, d: Document, ideas: list[Idea], names: list[str], cap: int) -> str | None:
+    """One post as written: the whole of it when it is short and mostly about the section's themes, else the lead and the windows
+    around its ideas' lines, merged, cut to `cap` characters (the windows that fit, in order of the post). None if unreadable."""
+    try:
+        lines = corpus.read_lines(d.path)
+    except Exception:
+        log.warning("report evidence: cannot read post %s, its summary stands in", d.path, exc_info=True)
+        return None
+    first = _body_start(lines)  # lines before this are the file's header
+    head = f"POST {d.title} [themes: {', '.join(names)}]"
+    stored = len((d.metadata_json or {}).get("ideas") or []) or 1
+    if len(d.clean_text or "") <= WHOLE_POST_CHARS and len(ideas) / stored >= WHOLE_POST_SHARE:
+        whole = "\n".join(_text(lines, first + 1, len(lines)))
+        if len(head) + len(whole) <= cap:
+            log.debug("report evidence: whole post %s (%d chars)", d.path, len(whole))
+            return f"{head}\n{whole}"
+    ranges = _idea_ranges(d, ideas, len(lines), first)
+    windows = _merge([(first + 1, min(len(lines), first + LEAD_LINES))] + ranges)
+    parts, used = [], len(head)
+    for a, b in windows:
+        text = "\n".join(_text(lines, a, b))
+        if not text:
+            continue
+        if parts and used + len(text) + 6 > cap:
+            break
+        parts.append(text[: max(cap - used, 200)] if not parts else text)
+        used += len(parts[-1]) + 6
+    return f"{head}\n" + "\n[...]\n".join(parts) if parts else None
+
+
+def _summary_line(idea: Idea, theme_name: str) -> str:
+    points = "; ".join(f"{x.get('label', '')}: {x.get('note', '')}".strip(": ") for x in idea.details[:SUMMARY_DETAILS]
+                       if isinstance(x, dict))
+    return f'- {idea.label}: {idea.note}' + (f" ({points})" if points else "") + f' (from "{idea.doc.title}", {theme_name})'
+
+
+def build(corpus: Corpus, section: Section, themes: dict[str, Theme], budget: int | None = None) -> Evidence:
+    """The evidence for one body or synthesis section: raw posts first, then summaries of the rest, within `budget` characters."""
+    budget = budget or BUDGETS.get(section.depth, BUDGETS["standard"])
+    items: list[tuple[Theme, Idea]] = [(themes[t], i) for t in section.theme_ids if t in themes for i in themes[t].ideas]
+    out = Evidence()
+    if not items:
+        log.warning("report evidence: section=%r has no ideas (themes %s)", section.heading, section.theme_ids)
+        return out
+    by_doc: dict[uuid.UUID, list[tuple[Theme, Idea]]] = {}
+    for t, i in items:
+        by_doc.setdefault(i.doc.id, []).append((t, i))
+
+    def key(entries: list[tuple[Theme, Idea]]) -> tuple:
+        d = entries[0][1].doc
+        stamp = d.published_at.timestamp() if d.published_at else 0
+        return (-len({t.id for t, _ in entries}), -len(entries), -stamp)
+
+    ranked = sorted(by_doc.values(), key=key)
+    wanted = RAW_POSTS.get(section.depth, 0)
+    raw_budget = (budget if len(ranked) <= wanted else int(budget * RAW_SHARE)) if wanted else 0
+    each = raw_budget // max(min(wanted, len(ranked)), 1)
+    rest: list[list[tuple[Theme, Idea]]] = []
+    for entries in ranked:
+        if out.raw_posts < wanted:
+            d = entries[0][1].doc
+            names = list(dict.fromkeys(t.name for t, _ in entries))
+            block = raw_post(corpus, d, [i for _, i in entries], names, each)
+            if block is not None:  # an unreadable post is passed over: the next one takes its place, its summary stands in
+                out.blocks.append(block)
+                out.posts.append(d.path)
+                out.raw_posts += 1
+                continue
+        rest.append(entries)
+
+    summary_budget = max(budget - sum(len(b) for b in out.blocks), 0)
+    lists = [[_summary_line(i, t.name) for t, i in entries] for entries in rest]
+    lines, used, rank = [], 0, 0
+    while any(rank < len(x) for x in lists):
+        for x in lists:
+            if rank < len(x) and used + len(x[rank]) <= summary_budget:
+                lines.append(x[rank])
+                used += len(x[rank]) + 1
+        rank += 1
+        if used >= summary_budget:
+            break
+    if lines:
+        out.blocks.append("SUMMARIES of other posts\n" + "\n".join(lines))
+    out.posts += [e[0][1].doc.path for e in rest if e[0][1].doc.path not in out.posts]
+    log.info("report evidence: section=%r depth=%s themes=%s ideas=%d posts=%d raw_posts=%d summarised_posts=%d summary_lines=%d "
+             "chars=%d budget=%d", section.heading, section.depth, section.theme_ids, len(items), len(by_doc), out.raw_posts,
+             len(rest), len(lines), sum(len(b) for b in out.blocks), budget)
+    return out
+
+
+def scale_budgets(sections: list[Section], total: int) -> dict[str, int]:
+    """Section heading -> budget, the standard budgets scaled down together when they add up to more than `total`."""
+    wanted = {s.heading: BUDGETS.get(s.depth, BUDGETS["standard"]) for s in sections if s.role in ("body", "synthesis")}
+    factor = min(1.0, total / max(sum(wanted.values()), 1))
+    return {h: max(int(math.floor(b * factor)), 1_000) for h, b in wanted.items()}

backend/app/pipeline/report_themes.py

@@ -0,0 +1,280 @@
+"""Themes for a report: what a notebook's posts are about, and how much of it each thing is.
+
+A report no longer reads the posts' text to find out. Every post already has its key ideas stored (documents.metadata_json["ideas"],
+written by generate.extract_ideas, each with the lines it came from), so those ideas stand for the posts, however many are picked:
+
+  1. one model call (GroupThemes) names themes and says which ideas belong to which (it sees at most MAX_LISTED_IDEAS of them);
+  2. code files every other idea into a theme and counts: how many posts and ideas each theme has gives its weight, so the weights
+     are true for the whole selection and not for the sample the model saw. A model groups well and counts badly.
+
+The weights decide how much room a theme gets in the report (report_blueprint.py) and how much of the posts' own text it is written
+from (report_evidence.py). A theme the reader asked for is moved up a tier whatever its share."""
+
+import logging
+import time
+import uuid
+from collections import Counter
+from dataclasses import dataclass, field
+
+from sqlalchemy.orm import Session
+
+from app.config import settings
+from app.corpus import Corpus
+from app.llm import run
+from app.llm.provider import fast_lm
+from app.llm.signatures import GroupThemes
+from app.models import Document, Job, Notebook, Workspace
+from app.pipeline.generate import extract_ideas, ideas_fresh
+from app.pipeline.idea_pool import _tokens
+from app.pipeline.passages import _body_start, notebook_docs, workspace_docs
+from app.services.jobs import update_job
+from app.services.plans import effective_plan
+
+log = logging.getLogger(__name__)
+
+SMALL_SELECTION = 5  # posts or fewer: the posts are read whole, as a report always was
+MIN_FRESH_SHARE = 0.5  # fewer posts than this with ideas stored: read the posts' text as before
+MAX_LISTED_IDEAS = 300  # ideas the model sees; the rest are filed by code
+MAX_THEMES = 12
+MIN_THEMES = 2
+MAJOR_AT, MEDIUM_AT = 0.25, 0.10  # a theme's share of the report: major from, medium from
+POST_WEIGHT, IDEA_WEIGHT = 0.6, 0.4  # how many posts mention it counts for more than how many ideas
+CATCH_ALL = "More from your posts"
+OPENING_LINES = 8  # lines of a post's opening that stand for a post with no ideas stored yet
+
+
+class ThemesUnavailable(Exception):
+    """The ideas did not group into themes: the caller reads the posts as before."""
+
+
+@dataclass
+class Idea:
+    id: str
+    doc: Document
+    label: str
+    note: str
+    details: list[dict] = field(default_factory=list)
+    sources: list[dict] = field(default_factory=list)
+    bare: bool = False  # no ideas stored for this post: this is its title and opening
+
+
+@dataclass
+class Theme:
+    id: str
+    name: str
+    summary: str
+    ideas: list[Idea]
+    asked: bool = False  # the reader's request asks for it
+    weight: float = 0.0  # share of the whole, all themes add up to 1
+    tier: str = "minor"  # major | medium | minor
+    pinned: bool = False  # asked for: always given a deep section
+
+    @property
+    def doc_ids(self) -> set[uuid.UUID]:
+        return {i.doc.id for i in self.ideas}
+
+
+# The posts
+
+def select_docs(db: Session, workspace_id: uuid.UUID, notebook_id: uuid.UUID | None, params: dict) -> list[Document]:
+    """The posts a report is made from: the ones picked, or the notebook's, newest first. Not cut at ARTIFACT_MAX_POSTS: only
+    what the plan indexes (and REPORT_MAX_POSTS, when set) limits it."""
+    picked = [uuid.UUID(str(i)) for i in params.get("document_ids") or []]
+    nb = db.get(Notebook, notebook_id) if notebook_id else None
+    if picked:
+        docs = workspace_docs(db, workspace_id, picked)
+    elif nb:
+        docs = notebook_docs(db, nb.id)
+    else:
+        docs = []
+    cap = effective_plan(db, db.get(Workspace, workspace_id)).indexed_posts
+    if settings.report_max_posts > 0:
+        cap = min(cap, settings.report_max_posts) if cap and cap > 0 else settings.report_max_posts
+    chosen = docs[:cap] if cap and cap > 0 else docs
+    log.info("report posts: workspace=%s notebook=%s picked=%d found=%d used=%d plan_cap=%s report_max_posts=%s", workspace_id,
+             notebook_id, len(picked), len(docs), len(chosen), cap, settings.report_max_posts)
+    if len(chosen) < len(docs):
+        log.warning("report posts cut by the plan or REPORT_MAX_POSTS: workspace=%s found=%d used=%d", workspace_id, len(docs),
+                    len(chosen))
+    return chosen
+
+
+def ensure_ideas(db: Session, job: Job | None, workspace_id: uuid.UUID, docs: list[Document]) -> None:
+    """Extract the ideas of posts that have none yet, together, at most REPORT_INLINE_IDEAS of them. The rest are represented
+    by their opening; the background ideas job reaches them later."""
+    stale = [d for d in docs if not ideas_fresh(d)]
+    if not stale or settings.report_inline_ideas <= 0:
+        log.info("report ideas: workspace=%s posts=%d stale=%d inline_limit=%d, nothing extracted now", workspace_id, len(docs),
+                 len(stale), settings.report_inline_ideas)
+        return
+    started = time.monotonic()
+    result = extract_ideas(db, job, workspace_id, [str(d.id) for d in stale], parallel=True, limit=settings.report_inline_ideas)
+    for d in stale:
+        db.refresh(d)
+    log.info("report ideas: workspace=%s posts=%d stale=%d extracted=%s skipped=%s left_for_background=%d seconds=%.1f",
+             workspace_id, len(docs), len(stale), result.get("extracted"), result.get("skipped"),
+             sum(1 for d in stale if not ideas_fresh(d)), time.monotonic() - started)
+
+
+def fresh_share(docs: list[Document]) -> float:
+    return sum(1 for d in docs if ideas_fresh(d)) / max(len(docs), 1)
+
+
+def _opening_idea(d: Document, di: int, corpus: Corpus) -> Idea:
+    """A post with no ideas stored: its title, its topics and where its opening is, so it still counts and can be cited."""
+    meta = d.metadata_json or {}
+    tags = ", ".join(t["name"] for t in (meta.get("topics") or [])[:3] if t.get("name"))
+    try:
+        lines = corpus.read_lines(d.path)
+    except Exception:
+        lines = []
+    first = _body_start(lines) + 1 if lines else 1
+    sources = [{"path": d.path, "line_start": first, "line_end": min(first + OPENING_LINES, len(lines) or first)}]
+    return Idea(id=f"p{di}.0", doc=d, label=d.title[:80], bare=True, sources=sources,
+                note=f"Topics: {tags}" if tags else "Only the opening of this post was read.")
+
+
+def collect_ideas(docs: list[Document], corpus: Corpus) -> list[Idea]:
+    """Every post's stored ideas as Ideas with ids like p3.1 (the third post's second idea), or its opening when it has none."""
+    out: list[Idea] = []
+    for di, d in enumerate(docs):
+        stored = [i for i in ((d.metadata_json or {}).get("ideas") or []) if (i.get("label") or "").strip()] \
+            if ideas_fresh(d) else []
+        if not stored:
+            out.append(_opening_idea(d, di, corpus))
+            continue
+        for ii, i in enumerate(stored):
+            out.append(Idea(id=f"p{di}.{ii}", doc=d, label=i["label"].strip(), note=(i.get("note") or "").strip(),
+                            details=i.get("details") or [], sources=i.get("sources") or []))
+    log.info("report ideas collected: posts=%d ideas=%d posts_with_only_an_opening=%d", len(docs), len(out),
+             sum(1 for i in out if i.bare))
+    return out
+
+
+# Themes
+
+def listed_ideas(ideas: list[Idea]) -> list[Idea]:
+    """The ideas the model sees: all of them, or when there are too many, the same number from every post in turn."""
+    if len(ideas) <= MAX_LISTED_IDEAS:
+        return ideas
+    by_doc: dict[uuid.UUID, list[Idea]] = {}
+    for i in ideas:
+        by_doc.setdefault(i.doc.id, []).append(i)
+    lists, picked, rank = list(by_doc.values()), [], 0
+    while len(picked) < MAX_LISTED_IDEAS and any(rank < len(x) for x in lists):
+        for x in lists:
+            if rank < len(x) and len(picked) < MAX_LISTED_IDEAS:
+                picked.append(x[rank])
+        rank += 1
+    return picked
+
+
+def _file_leftovers(themes: list[Theme], leftovers: list[Idea]) -> None:
+    """Every idea the model did not place goes to the theme its post's other ideas are mostly in, else the theme whose words it
+    shares most, else a catch-all theme: the way the Mind Constellation files what the model leaves out."""
+    by_doc: dict[uuid.UUID, Counter] = {}
+    for ti, t in enumerate(themes):
+        for i in t.ideas:
+            by_doc.setdefault(i.doc.id, Counter())[ti] += 1
+    theme_words = [_tokens(" ".join([t.name, t.summary] + [i.label for i in t.ideas[:20]])) for t in themes]
+    # A word in most themes ("idea", "post") says nothing about which one an idea is about.
+    common = {w for w, n in Counter(w for tw in theme_words for w in tw).items() if n > max(1, len(themes) // 2)}
+    theme_words = [tw - common for tw in theme_words]
+    catch: Theme | None = None
+    for idea in leftovers:
+        counts = by_doc.get(idea.doc.id)
+        if counts:
+            themes[counts.most_common(1)[0][0]].ideas.append(idea)
+            continue
+        words = _tokens(f"{idea.label} {idea.note}") - common
+        best, score = max(((ti, len(words & tw)) for ti, tw in enumerate(theme_words)), key=lambda x: x[1])
+        if score > 0:
+            themes[best].ideas.append(idea)
+            continue
+        if catch is None:
+            catch = Theme(id="", name=CATCH_ALL, summary="Ideas that fit none of the other themes.", ideas=[])
+            themes.append(catch)
+        catch.ideas.append(idea)
+    log.info("report leftover ideas filed: leftovers=%d catch_all=%d", len(leftovers), len(catch.ideas) if catch else 0)
+
+
+def weigh(themes: list[Theme], total_posts: int, total_ideas: int) -> None:
+    """Each theme's share of the whole, from how many posts and ideas it has (not from anything the model said), and its tier. A
+    theme the reader asked for moves up one tier and is pinned. If nothing reached major, the heaviest theme becomes major."""
+    raw = [POST_WEIGHT * len(t.doc_ids) / max(total_posts, 1) + IDEA_WEIGHT * len(t.ideas) / max(total_ideas, 1) for t in themes]
+    total = sum(raw) or 1.0
+    for t, r in zip(themes, raw, strict=True):
+        t.weight = round(r / total, 4)
+        t.tier = "major" if t.weight >= MAJOR_AT else "medium" if t.weight >= MEDIUM_AT else "minor"
+    if themes and not any(t.tier == "major" for t in themes):
+        max(themes, key=lambda t: t.weight).tier = "major"
+    for t in themes:
+        if t.asked:
+            t.pinned = True
+            t.tier = {"minor": "medium", "medium": "major"}.get(t.tier, t.tier)
+
+
+def _relations(raw: list[dict] | None, themes: list[Theme]) -> list[dict]:
+    by_name = {t.name.lower(): t.id for t in themes}
+    out = []
+    for r in raw or []:
+        a, b = by_name.get(str(r.get("a", "")).strip().lower()), by_name.get(str(r.get("b", "")).strip().lower())
+        relation = (r.get("relation") or "").strip()
+        if a and b and a != b and relation:
+            out.append({"a": a, "b": b, "relation": relation[:200]})
+    return out[:8]
+
+
+def group_themes(db: Session, job: Job | None, workspace_id: uuid.UUID, title: str, request: str,
+                 ideas: list[Idea]) -> tuple[list[Theme], list[dict]]:
+    """Themes with their weights, and how they relate (by theme id). Raises ThemesUnavailable when the answer is not usable."""
+    by_id = {i.id: i for i in ideas}
+    listed = listed_ideas(ideas)
+    listing = [f"{i.id} | {i.label}: {i.note[:140]}" for i in listed]
+    log.info("report themes: asking the model workspace=%s ideas=%d listed=%d (cap %d) posts=%d", workspace_id, len(ideas),
+             len(listed), MAX_LISTED_IDEAS, len({i.doc.id for i in ideas}))
+    started = time.monotonic()
+    out = run.predict(GroupThemes, db=db, workspace_id=workspace_id, job=job, lm=fast_lm(), title=title,
+                      request=request, ideas=listing)
+    themes: list[Theme] = []
+    taken: set[str] = set()
+    dropped = 0
+    for t in out.get("themes") or []:
+        name = (t.get("name") or "").strip()
+        wanted = list(t.get("idea_ids") or [])
+        mine = [by_id[i] for i in wanted if i in by_id and i not in taken]
+        dropped += len(wanted) - len(mine)  # unknown ids, or ideas another theme already took
+        if not name or not mine:
+            log.info("report theme skipped: name=%r usable_ideas=%d", name, len(mine))
+            continue
+        taken.update(i.id for i in mine)
+        themes.append(Theme(id="", name=name[:80], summary=(t.get("summary") or "").strip()[:400], ideas=mine,
+                            asked=bool(t.get("matches_request"))))
+        if len(themes) == MAX_THEMES:
+            break
+    log.info("report themes: model answered themes=%d usable=%d ids_dropped=%d seconds=%.1f", len(out.get("themes") or []),
+             len(themes), dropped, time.monotonic() - started)
+    if len(themes) < MIN_THEMES:
+        log.warning("report themes unusable: usable=%d needed=%d", len(themes), MIN_THEMES)
+        raise ThemesUnavailable("the ideas did not group into themes")
+    _file_leftovers(themes, [i for i in ideas if i.id not in taken])
+    for n, t in enumerate(themes, start=1):
+        t.id = f"t{n}"
+    weigh(themes, len({i.doc.id for i in ideas}), len(ideas))
+    relations = _relations(out.get("relations"), themes)
+    for t in themes:
+        log.info("report theme: id=%s name=%r weight=%.3f tier=%s asked=%s pinned=%s posts=%d ideas=%d", t.id, t.name, t.weight,
+                 t.tier, t.asked, t.pinned, len(t.doc_ids), len(t.ideas))
+    log.info("report theme relations: model=%d kept=%d", len(out.get("relations") or []), len(relations))
+    return themes, relations
+
+
+def theme_summary(t: Theme) -> dict:
+    """What is kept with the report about a theme."""
+    return {"id": t.id, "name": t.name, "summary": t.summary, "weight": t.weight, "tier": t.tier, "pinned": t.pinned,
+            "posts": len(t.doc_ids), "ideas": len(t.ideas)}
+
+
+def progress(db: Session, job: Job | None, value: float, message: str) -> None:
+    if job:
+        update_job(db, job, progress=value, message=message)

backend/app/services/artifact_feedback.py

@@ -0,0 +1,56 @@
+"""Thumbs up or down on generated reports, quizzes, flashcards and infographics: what can be rated, why a thumbs down can be
+given, and how the ratings ride along on the artifacts the app lists."""
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.models import Artifact, ArtifactFeedback, QuizAttempt
+
+# What each kind can be marked down for (the ids the app sends; anything else is dropped).
+REASONS: dict[str, set[str]] = {
+    "report": {"inaccurate", "missed_points", "structure", "tone", "too_long", "too_short", "other"},
+    "quiz": {"wrong_answers", "too_easy", "too_hard", "unclear", "off_topic", "other"},
+    "flashcards": {"inaccurate", "too_basic", "too_detailed", "unclear", "other"},
+    "infographic": {"messy_layout", "cut_off", "missing_content", "look", "hard_to_read", "other"},
+}
+RATEABLE = tuple(REASONS)
+
+
+def feedback_out(f: ArtifactFeedback | None) -> dict | None:
+    if not f:
+        return None
+    return {"rating": "up" if f.rating > 0 else "down", "reasons": f.reasons or [], "comment": f.comment}
+
+
+def attempt_out(a: QuizAttempt | None) -> dict | None:
+    return {"score": a.score, "total": a.total, "answers": a.answers or []} if a else None
+
+
+def attach(db: Session, user_id: uuid.UUID, items: list[dict]) -> list[dict]:
+    """Add `feedback` (this person's rating, or None) to each serialized artifact that can be rated. One query."""
+    ids = [uuid.UUID(i["id"]) for i in items if i.get("type") in RATEABLE]
+    rows = {f.artifact_id: f for f in db.scalars(select(ArtifactFeedback).where(
+        ArtifactFeedback.artifact_id.in_(ids), ArtifactFeedback.user_id == user_id))} if ids else {}
+    quiz_ids = [uuid.UUID(i["id"]) for i in items if i.get("type") == "quiz"]
+    attempts = {a.artifact_id: a for a in db.scalars(select(QuizAttempt).where(
+        QuizAttempt.artifact_id.in_(quiz_ids), QuizAttempt.user_id == user_id))} if quiz_ids else {}
+    for i in items:
+        if i.get("type") in RATEABLE:
+            i["feedback"] = feedback_out(rows.get(uuid.UUID(i["id"])))
+        if i.get("type") == "quiz":
+            i["attempt"] = attempt_out(attempts.get(uuid.UUID(i["id"])))
+    return items
+
+
+def snapshot(a: Artifact) -> dict:
+    """What the artifact was when it was rated: enough to tell what a rating is about."""
+    c = a.content_json or {}
+    inner = c.get("content") if isinstance(c.get("content"), dict) else {}
+    keep = {k: c.get(k) for k in ("title", "prompt", "source", "theme", "format", "template_id", "difficulty", "question_count",
+                                  "card_count", "language", "topic") if c.get(k) is not None}
+    if a.type == "infographic":
+        keep["layout"] = "composed" if "body_html" in inner else "fixed"
+        keep["fit"] = inner.get("fit")
+    return keep

backend/app/services/report_suggestions.py

@@ -0,0 +1,148 @@
+"""The suggested templates in the Create report dialog: written by the AI from each post's stored ideas and topics, kept by a hash of
+what it read, prepared in the background as soon as ideas are extracted, and served at once whenever the dialog opens."""
+
+import hashlib
+import logging
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app.config import settings
+from app.llm import run
+from app.llm.provider import suggest_templates_lm
+from app.llm.signatures import SuggestReportTemplates
+from app.models import Document, Notebook, ReportTemplateCache
+from app.pipeline.generate import ideas_fresh
+from app.pipeline.material import max_posts
+from app.pipeline.passages import notebook_docs
+from app.services.jobs import create_job, pending_job
+
+log = logging.getLogger("notestack")
+
+SUGGEST_ITEMS = 4  # sources the AI reads to suggest templates
+SUMMARY_IDEAS = 3  # a post's stored ideas shown to the AI
+SUMMARY_CHARS = 350  # most characters of one post's summary
+WARM_NOTEBOOKS = 30  # notebooks prepared per run (the most recently changed)
+KEEP_PER_WORKSPACE = 10  # stored sets kept per workspace; the oldest go
+
+
+def summary(d: Document) -> str:
+    """A post as the AI sees it when suggesting templates: its title, its topics and the key ideas already extracted from it (the
+    ones the Mind Constellation and the topic map are built from), a few hundred characters at most."""
+    meta = d.metadata_json or {}
+    ideas = [f"{i['label'].strip()}: {(i.get('note') or '').strip()}" for i in meta.get("ideas") or [] if (i.get("label") or "").strip()]
+    tags = [t["name"] for t in meta.get("topics") or [] if t.get("name")][:3]
+    head = d.title + (f"\nTopics: {', '.join(tags)}" if tags else "")
+    return (head + "\n" + "\n".join(f"- {x}" for x in ideas[:SUMMARY_IDEAS]))[:SUMMARY_CHARS]
+
+
+def stable_order(docs: list[Document]) -> list[Document]:
+    """The posts in an order that belongs to the posts, not to the selection: the same posts come first whenever they are picked.
+    The templates are read from the first few, so ticking or unticking any other post gives the same input, the same key, and the
+    templates kept for it (the ones prepared in the background for the whole notebook) are served at once, not written again."""
+    return sorted(docs, key=lambda d: hashlib.sha256(str(d.id).encode()).hexdigest())
+
+
+def suggestion_items(material: dict[str, str], docs: list[Document]) -> list[str]:
+    """What the AI reads: each post's stored summary when it has one (else the start of the post, as `material` holds it), or for
+    chats their first exchange. At most SUGGEST_ITEMS, from the posts that come first in stable_order."""
+    if not docs:
+        return list(material.values())[:SUGGEST_ITEMS]
+    out = []
+    for d in stable_order(docs):
+        item = summary(d) if ideas_fresh(d) else material.get(str(d.id))
+        if item:
+            out.append(item)
+        if len(out) == SUGGEST_ITEMS:
+            break
+    return out
+
+
+def cache_key(items: list[str], topic: str) -> str:
+    return hashlib.sha256(("\x1f".join(items) + "\x1e" + (topic or "").strip()).encode()).hexdigest()
+
+
+def _clean(out: dict) -> list[dict]:
+    seen, found = set(), []
+    for t in out.get("templates") or []:
+        name, prompt = (t.get("name") or "").strip(), (t.get("prompt") or "").strip()
+        if not name or not prompt or name.lower() in seen:
+            continue
+        seen.add(name.lower())
+        found.append({"id": f"suggested-{len(found) + 1}", "name": name[:60],
+                      "description": (t.get("description") or "").strip()[:200], "prompt": prompt[:1500]})
+    return found[:4]
+
+
+def suggest(db: Session, workspace_id: uuid.UUID, items: list[str], topic: str = "") -> list[dict]:
+    """Four templates for these sources: the stored ones when the same sources were seen before, else written now (one AI call) and
+    stored. A failed or empty answer is never stored. Never raises."""
+    if not items:
+        return []
+    key = cache_key(items, topic)
+    hit = db.scalar(select(ReportTemplateCache).where(ReportTemplateCache.workspace_id == workspace_id, ReportTemplateCache.key == key))
+    if hit and hit.templates:
+        log.info("report templates: kept set served workspace=%s key=%s", workspace_id, key[:10])
+        return hit.templates
+    log.info("report templates: no kept set, asking the model workspace=%s key=%s items=%d", workspace_id, key[:10], len(items))
+    try:
+        out = run.predict(SuggestReportTemplates, db=db, workspace_id=workspace_id, lm=suggest_templates_lm(), items=items,
+                          topic=(topic or "").strip() or "(none)")
+    except Exception:
+        log.warning("template suggestions failed", exc_info=True)
+        return []
+    templates = _clean(out)
+    if templates:
+        _store(db, workspace_id, key, templates)
+    return templates
+
+
+def _store(db: Session, workspace_id: uuid.UUID, key: str, templates: list[dict]) -> None:
+    try:
+        row = db.scalar(select(ReportTemplateCache).where(ReportTemplateCache.workspace_id == workspace_id, ReportTemplateCache.key == key))
+        if row:
+            row.templates = templates
+        else:
+            db.add(ReportTemplateCache(workspace_id=workspace_id, key=key, templates=templates))
+        db.commit()
+    except IntegrityError:  # another request stored the same set first
+        db.rollback()
+        return
+    old = db.scalars(select(ReportTemplateCache).where(ReportTemplateCache.workspace_id == workspace_id)
+                     .order_by(ReportTemplateCache.updated_at.desc()).offset(KEEP_PER_WORKSPACE)).all()
+    for row in old:
+        db.delete(row)
+    if old:
+        db.commit()
+
+
+def queue_warmup(db: Session, workspace_id: uuid.UUID) -> None:
+    """Have the templates for the workspace's notebooks prepared in the background (once at a time). Called when ideas have been
+    extracted and when posts join a notebook, so they are ready before anyone opens the dialog."""
+    if settings.llm_api_key and not pending_job(db, workspace_id, "report_templates"):
+        create_job(db, workspace_id, "report_templates", {}, max_attempts=2)
+
+
+def warm_workspace(db: Session, workspace_id: uuid.UUID) -> int:
+    """Write and keep the templates of each recently changed notebook for the posts its dialog starts with (the newest ones, as the
+    dialog ticks them), skipping a notebook whose posts have mostly no stored ideas yet (they are prepared once the ideas land) and
+    any set already stored. Returns how many were written."""
+    from app.routers.videos import _excerpt, is_locked  # the dialog's own preview of a post, so the keys match
+
+    written = 0
+    for nb in db.scalars(select(Notebook).where(Notebook.workspace_id == workspace_id)
+                         .order_by(Notebook.updated_at.desc()).limit(WARM_NOTEBOOKS)):
+        docs = [d for d in notebook_docs(db, nb.id) if not is_locked(d)][:max_posts()]
+        if not docs or sum(1 for d in docs if ideas_fresh(d)) * 2 < len(docs):
+            continue
+        docs.sort(key=lambda d: d.published_at or d.created_at, reverse=True)
+        each = 800 if len(docs) == 1 else 400
+        material = {str(d.id): "\n".join(p for p in (d.title or "", _excerpt(d.clean_text, each)) if p) for d in docs}
+        items = suggestion_items(material, docs)
+        key = cache_key(items, "")
+        if items and not db.scalar(select(ReportTemplateCache.id).where(ReportTemplateCache.workspace_id == workspace_id,
+                                                                         ReportTemplateCache.key == key)):
+            written += bool(suggest(db, workspace_id, items, ""))
+    return written

backend/tests/test_idea_pool.py

@@ -0,0 +1,279 @@
+"""Flashcards (always) and quizzes (above ARTIFACT_MAX_POSTS posts) made from the ideas already extracted from each post
+(pipeline/idea_pool.py). The model is always faked here."""
+
+import random
+import re
+import uuid
+
+import pytest
+from sqlalchemy import select
+
+from app.config import settings
+from app.corpus import Corpus
+from app.llm import run
+from app.models import Document, Job, Workspace
+from app.pipeline import idea_pool
+from app.pipeline.material import load_material, max_posts
+from app.services import report_suggestions
+from tests.conftest import last_code
+
+THEMES = ["Pricing", "Audience Growth", "Writing Craft"]
+
+
+@pytest.fixture()
+def owner(client, db_session):
+    client.post("/api/auth/email/register/start", json={"email": "ada@example.com", "password": "stardust-42", "name": "Ada"})
+    r = client.post("/api/auth/email/register/verify", json={"email": "ada@example.com", "code": last_code()})
+    return {"Authorization": f"Bearer {r.json()['access_token']}"}, db_session.scalar(select(Workspace))
+
+
+def make_posts(db, ws, n: int, *, with_ideas: int | None = None, ideas_each: int = 3, start: int = 0, body: int = 11) -> list[Document]:
+    """n indexed posts in the corpus, spread over three themes; the first `with_ideas` have stored ideas (all by default)."""
+    with_ideas = n if with_ideas is None else with_ideas
+    files, docs = {}, []
+    for i in range(start, start + n):
+        theme = THEMES[i % len(THEMES)]
+        lines = ["---", f'title: "Post {i}"', "---", "", f"# Post {i}", ""] + [f"Sentence {k} about {theme.lower()} in post {i}." for k in range(1, body + 1)]
+        path = f"sources/x/post-{i}.md"
+        files[path] = "\n".join(lines) + "\n"
+        d = Document(workspace_id=ws.id, title=f"Post {i} on {theme}", url=f"https://x.test/{i}", path=path, content_hash=f"h{i}",
+                     clean_text=" ".join(lines), metadata_json={})
+        if i - start < with_ideas:
+            d.metadata_json = {"ideas_hash": f"h{i}", "ideas": [
+                {"label": f"{theme} idea {i}.{k}", "note": f"What post {i} says about {theme.lower()}.",
+                 "sources": [{"path": path, "line_start": 7 + k, "line_end": 9 + k}], "details": []} for k in range(ideas_each)]}
+        db.add(d)
+        docs.append(d)
+    db.commit()
+    Corpus(ws.id).write_files(files)
+    return docs
+
+
+def idea_lines(material: list[str]) -> list[str]:
+    return [m for m in material if m.startswith("IDEA [")]
+
+
+def test_a_sample_is_small_cited_and_spread_over_the_posts(owner, db_session):
+    _, ws = owner
+    docs = make_posts(db_session, ws, 60)
+    material = idea_pool.sample(db_session, ws.id, docs, rng=random.Random(1))
+    lines = idea_lines(material)
+    assert material[0] == idea_pool.FORMAT_NOTE and len(lines) == settings.artifact_idea_sample == 30
+    assert sum(len(m) for m in material) < 8_000  # about 1,500 tokens, whatever the size of the selection
+    assert all(re.fullmatch(r"IDEA \[sources/x/post-\d+\.md lines \d+-\d+\] .+ idea \d+\.\d: What post \d+ says about .+\.", m) for m in lines)
+    per_post = [m.split("[")[1].split(" ")[0] for m in lines]
+    assert max(per_post.count(p) for p in set(per_post)) <= idea_pool.IDEAS_PER_POST and len(set(per_post)) >= 15
+    assert lines != idea_lines(idea_pool.sample(db_session, ws.id, docs, rng=random.Random(2)))  # a fresh draw each time
+    assert lines == idea_lines(idea_pool.sample(db_session, ws.id, docs, rng=random.Random(1)))  # the same draw for the same seed
+    assert db_session.scalars(select(Job)).all() == []  # nothing is queued or extracted here
+
+
+def test_a_small_selection_sends_all_its_ideas_and_a_topic_comes_first(owner, db_session):
+    _, ws = owner
+    few = make_posts(db_session, ws, 3, ideas_each=5)  # 15 ideas, fewer than the sample: all of them, however many per post
+    assert len(idea_lines(idea_pool.sample(db_session, ws.id, few))) == 15
+    docs = make_posts(db_session, ws, 30, start=100)
+    picked = idea_lines(idea_pool.sample(db_session, ws.id, docs, topic="audience growth", size=10, rng=random.Random(3)))
+    assert len(picked) == 10 and all("audience growth" in m.lower() for m in picked)  # ten of the matching ideas, before any other
+
+
+def test_posts_with_no_ideas_get_a_short_opening_and_chats_only_their_end(owner, db_session):
+    _, ws = owner
+    docs = make_posts(db_session, ws, 12, with_ideas=5)
+    material = idea_pool.sample(db_session, ws.id, docs, chats=["x" * 50_000, "y" * 50_000], rng=random.Random(4))
+    openings = [m for m in material if m.startswith("FILE ")]
+    assert len(openings) == idea_pool.MAX_OPENINGS and all(len(o) < 1_100 for o in openings)
+    assert [len(m) for m in material[-2:]] == [idea_pool.CHAT_BUDGET // 2] * 2
+    assert db_session.scalars(select(Job)).all() == []
+
+
+def test_limits_and_budgets_come_from_settings(owner, db_session, monkeypatch):
+    from app.pipeline.passages import passages_for
+
+    assert max_posts() == 20
+    monkeypatch.setattr(settings, "artifact_max_posts", 5)
+    assert max_posts() == 5
+    monkeypatch.undo()
+    _, ws = owner
+    docs = make_posts(db_session, ws, 20, with_ideas=0, body=300)  # long posts: each fills whatever it is given
+    text = lambda: sum(len(p) for p in passages_for(Corpus(ws.id), docs))  # noqa: E731
+    full = text()
+    assert 20 * 5_500 < full < 20 * 6_500  # 120,000 characters shared by 20 posts: about 6,000 each
+    monkeypatch.setattr(settings, "artifact_passage_budget", 40_000)
+    mid = text()
+    assert 20 * 1_500 < mid < 20 * 2_500  # 2,000 each
+    monkeypatch.setattr(settings, "artifact_passage_budget", 1)  # the floor is 1,500 characters a post
+    assert 20 * 1_000 < text() < mid
+
+
+def _notebook(client, owner, docs):
+    headers, _ = owner
+    return client.post("/api/notebooks", json={"title": "Big", "document_ids": [str(d.id) for d in docs]}, headers=headers).json()
+
+
+def test_when_ideas_are_used_instead_of_the_posts_text(owner, db_session):
+    _, ws = owner
+    nb = uuid.uuid4()  # an unknown notebook: only the picked posts count
+    big = make_posts(db_session, ws, 30)
+    ids = [str(d.id) for d in big]
+    quiz_20 = load_material(db_session, ws.id, nb, {"document_ids": ids[:20]}, what="quiz", large_ok=True)
+    assert quiz_20.mode == "passages" and len(quiz_20.text) == 20  # up to the limit: the text, exactly as before
+    quiz_30 = load_material(db_session, ws.id, nb, {"document_ids": ids}, what="quiz", large_ok=True)
+    assert quiz_30.mode == "ideas" and len(quiz_30.docs) == 30 and quiz_30.text == []
+    report = load_material(db_session, ws.id, nb, {"document_ids": ids}, what="report")
+    assert report.mode == "passages" and len(report.docs) == 20  # a report still reads its first posts' text
+    cards_3 = load_material(db_session, ws.id, nb, {"document_ids": ids[:3]}, what="flashcard set", large_ok=True, ideas_always=True)
+    assert cards_3.mode == "ideas" and len(cards_3.docs) == 3  # flashcards: always the ideas, even from three posts
+    # Ideas not stored yet: the posts' text is read (the first 20 when there are more), as it always was
+    bare = make_posts(db_session, ws, 30, with_ideas=0, start=200)
+    bare_ids = [str(d.id) for d in bare]
+    assert load_material(db_session, ws.id, nb, {"document_ids": bare_ids}, what="quiz", large_ok=True).mode == "passages"
+    big_bare = load_material(db_session, ws.id, nb, {"document_ids": bare_ids}, what="quiz", large_ok=True)
+    assert len(big_bare.docs) == 20 and len(big_bare.text) == 20
+    few_bare = load_material(db_session, ws.id, nb, {"document_ids": bare_ids[:3]}, what="flashcard set", large_ok=True, ideas_always=True)
+    assert few_bare.mode == "passages" and len(few_bare.text) == 3
+    # Half or more with ideas: the ideas, and a short opening for the rest
+    half = make_posts(db_session, ws, 4, with_ideas=2, start=300)
+    assert load_material(db_session, ws.id, nb, {"document_ids": [str(d.id) for d in half]}, what="flashcard set", large_ok=True,
+                         ideas_always=True).mode == "ideas"
+
+
+def _cited(inputs: dict) -> list[dict]:
+    """A source for each idea line, copied from its tag the way the model is told to."""
+    tags = [re.match(r"IDEA \[(\S+) lines (\d+)-(\d+)\]", m) for m in inputs["material"]]
+    return [{"path": t[1], "line_start": int(t[2]), "line_end": int(t[3])} for t in tags if t]
+
+
+def test_a_big_quiz_is_one_call_over_a_sample_of_ideas(client, owner, db_session, run_jobs, monkeypatch):
+    headers, ws = owner
+    docs = make_posts(db_session, ws, 40)
+    nb = _notebook(client, owner, docs)
+    calls: list[dict] = []
+
+    def predict(signature, *, db, workspace_id, job=None, lm=None, **inputs):
+        assert signature.__name__ == "GenerateQuiz"
+        calls.append(inputs)
+        cited = _cited(inputs)
+        return {"questions": [{"type": "multiple_choice", "question": f"Question {k}?", "options": ["a", "b"], "correct": [0],
+                               "explanation": "", "sources": [cited[k]]} for k in range(inputs["count"])]}
+
+    monkeypatch.setattr(run, "predict", predict)
+    monkeypatch.setattr(run, "predict_many", lambda *a, **k: pytest.fail("one call"))
+    art = client.post("/api/artifacts/generate", json={"type": "quiz", "notebook_id": nb["id"], "document_ids": [str(d.id) for d in docs],
+                      "question_types": ["multiple_choice"]}, headers=headers).json()
+    run_jobs()
+    done = client.get(f"/api/artifacts/{art['id']}", headers=headers).json()
+    assert done["status"] == "ready", done["content"]
+    assert len(calls) == 1 and calls[0]["count"] == 10 and calls[0]["material"][0] == idea_pool.FORMAT_NOTE
+    assert len(idea_lines(calls[0]["material"])) == 30
+    qs = done["content"]["questions"]
+    assert len(qs) == 10 and all(q["sources"] and q["sources"][0]["document_id"] and q["sources"][0]["quote"] for q in qs)  # lines verified
+    assert len(done["content"]["source"]["document_ids"]) == 40
+    assert db_session.scalars(select(Job).where(Job.kind == "ideas")).all() == []
+
+
+def test_flashcards_use_the_ideas_for_any_size_of_selection_but_not_for_chats(client, owner, db_session, run_jobs, monkeypatch):
+    headers, ws = owner
+    docs = make_posts(db_session, ws, 3, ideas_each=4)
+    nb = _notebook(client, owner, docs)
+    calls: list[list[str]] = []
+
+    def predict(signature, *, db, workspace_id, job=None, lm=None, **inputs):
+        calls.append(inputs["material"])
+        cited = _cited(inputs) or [{"path": docs[0].path, "line_start": 1, "line_end": 2}]
+        return {"cards": [{"front": f"Front {k}", "back": "Back.", "sources": [cited[k % len(cited)]]} for k in range(inputs["count"])]}
+
+    monkeypatch.setattr(run, "predict", predict)
+    art = client.post("/api/artifacts/generate", json={"type": "flashcards", "notebook_id": nb["id"],
+                      "document_ids": [str(d.id) for d in docs]}, headers=headers).json()
+    run_jobs()
+    done = client.get(f"/api/artifacts/{art['id']}", headers=headers).json()
+    assert done["status"] == "ready" and done["content"]["card_count"] == 16
+    assert calls[0][0] == idea_pool.FORMAT_NOTE and len(idea_lines(calls[0])) == 12  # all twelve ideas, no post text
+    assert not any(m.startswith("FILE ") for m in calls[0])
+    assert all(c["sources"] and c["sources"][0]["document_id"] for c in done["content"]["cards"])
+
+
+def test_a_quiz_or_flashcards_take_any_number_of_posts_and_the_limits_are_served(client, owner, db_session, monkeypatch):
+    headers, ws = owner
+    docs = make_posts(db_session, ws, 130)
+    ids = [str(d.id) for d in docs]
+    nb = _notebook(client, owner, docs)
+    assert client.get("/api/settings/limits", headers=headers).json() == {"posts": 20}
+    big = load_material(db_session, ws.id, uuid.UUID(nb["id"]), {"document_ids": ids}, what="quiz", large_ok=True)
+    assert big.mode == "ideas" and len(big.docs) == 130 and big.text == []  # all of them count; the sample stays the same size
+    assert len(idea_lines(idea_pool.sample(db_session, ws.id, big.docs))) == settings.artifact_idea_sample
+    cap = load_material(db_session, ws.id, uuid.UUID(nb["id"]), {"document_ids": ids}, what="report")
+    assert len(cap.docs) == 20  # a report still reads its first posts
+    monkeypatch.setattr(run, "predict", lambda *a, **k: {"questions": []})
+    for kind in ("quiz", "flashcards"):  # no refusal for a big selection
+        r = client.post("/api/artifacts/generate", json={"type": kind, "notebook_id": nb["id"], "document_ids": ids}, headers=headers)
+        assert r.status_code == 200, r.text
+
+
+def test_a_passage_leaves_out_the_file_header_and_keeps_the_line_numbers(owner, db_session):
+    from app.pipeline.passages import passages_for
+
+    _, ws = owner
+    doc = make_posts(db_session, ws, 1, with_ideas=0)[0]
+    text = passages_for(Corpus(ws.id), [doc])[0]
+    assert text.startswith(f"FILE {doc.path} ({doc.title})\n7| Sentence 1 about")  # no ---, title, url, date or "# Post" lines
+    assert "---" not in text and "# Post" not in text and "title:" not in text
+    assert "11| Sentence 5" in text  # numbered as in the file, so a cited line is still the right one
+
+
+def test_a_quiz_reads_posts_with_its_own_smaller_budget(client, owner, db_session, run_jobs, monkeypatch):
+    headers, ws = owner
+    docs = make_posts(db_session, ws, 20, with_ideas=0, body=300)
+    nb = _notebook(client, owner, docs)
+    sizes: dict[str, int] = {}
+
+    def predict(signature, *, db, workspace_id, job=None, lm=None, **inputs):
+        sizes[signature.__name__] = sum(len(m) for m in inputs["material"])
+        raise RuntimeError("stop here: only the size of what was sent is wanted")
+
+    monkeypatch.setattr(run, "predict", predict)
+    ids = [str(d.id) for d in docs]
+    for kind in ("quiz", "report"):
+        client.post("/api/artifacts/generate", json={"type": kind, "notebook_id": nb["id"], "document_ids": ids}, headers=headers)
+    run_jobs()
+    assert settings.artifact_quiz_passage_budget == 60_000
+    assert sizes["GenerateQuiz"] < 0.6 * sizes["WriteReport"]  # a quiz's 60,000 characters against a report's 120,000
+
+
+
+def test_suggested_report_templates_read_each_posts_stored_summary(client, owner, db_session, monkeypatch):
+    headers, ws = owner
+    docs = make_posts(db_session, ws, 6, with_ideas=4, ideas_each=6)  # the last two posts have no stored ideas yet
+    for d in docs[:4]:
+        d.metadata_json = {**d.metadata_json, "topics": [{"name": "Pricing", "weight": 0.9}, {"name": "Growth", "weight": 0.5}]}
+    db_session.commit()
+    seen: list[dict] = []
+
+    def predict(signature, *, db, workspace_id, job=None, lm=None, **inputs):
+        assert signature.__name__ == "SuggestReportTemplates"
+        seen.append(inputs)
+        return {"templates": [{"name": f"Template {n}", "description": "d", "prompt": "p"} for n in range(4)]}
+
+    monkeypatch.setattr(run, "predict", predict)
+    r = client.post("/api/reports/suggest", json={"document_ids": [str(d.id) for d in docs]}, headers=headers)
+    assert r.status_code == 200 and len(r.json()["templates"]) == 4
+    items = seen[0]["items"]
+    assert len(items) == report_suggestions.SUGGEST_ITEMS  # at most this many sources, however many are selected (newest first)
+    summaries = [i for i in items if "\n- " in i]
+    starts = [i for i in items if "\n- " not in i]
+    assert len(summaries) == 2 and len(starts) == 2  # the two newest posts have no stored ideas: read by their start
+    for item in summaries:
+        ideas = report_suggestions.SUMMARY_IDEAS
+        assert "Topics: Pricing, Growth" in item and item.count("\n- ") == ideas and len(item) <= report_suggestions.SUMMARY_CHARS
+        assert " idea " in item and "Sentence 1 about" not in item  # the stored ideas, not the post text
+    assert all("Sentence" in i for i in starts)
+    # A post with no stored ideas is still read, by its start
+    r = client.post("/api/reports/suggest", json={"document_ids": [str(docs[13].id)]}, headers=headers)
+    assert r.status_code == 200 and "Sentence" in seen[1]["items"][0]
+
+
+def test_the_fast_models_output_cap_is_a_setting():
+    from app.llm.provider import fast_lm
+
+    assert settings.llm_fast_max_tokens == 6000 and fast_lm().kwargs["max_tokens"] == 6000  # quizzes and flashcards write under 3,000

backend/tests/test_report_blocks.py

@@ -0,0 +1,91 @@
+"""remove_block: a removed visual's offer to add it again comes back, so the reader is never stuck with no way in.
+copy_block: reusing an artifact the user already made points the new block at it, never raising for one that is ready."""
+
+import uuid
+
+import pytest
+
+from app.models import Artifact
+from app.pipeline.generate import NothingToDo
+from app.pipeline.report import copy_block, remove_block
+
+
+def _content(blocks, suggestions=None):
+    return {"blocks": blocks, "suggestions": suggestions or []}
+
+
+def test_removing_a_visual_restores_its_add_offer():
+    content = _content([
+        {"id": "b1", "type": "prose", "text": "intro"},
+        {"id": "b2", "type": "quiz", "after": "b1", "title": "Quiz"},
+        {"id": "b3", "type": "prose", "text": "more"},
+    ])
+    out = remove_block(content, "b2")
+    assert out is not None
+    assert [b["id"] for b in out["blocks"]] == ["b1", "b3"]
+    assert [s["kind"] for s in out["suggestions"]] == ["quiz"]
+    assert out["suggestions"][0]["after_block_id"] == "b1"
+
+
+def test_removing_leaves_an_existing_suggestion_of_the_same_kind_alone():
+    existing = {"id": "s1", "after_block_id": "b1", "kind": "quiz", "brief": "custom", "why": "custom"}
+    content = _content(
+        [{"id": "b1", "type": "prose", "text": "intro"}, {"id": "b2", "type": "quiz", "after": "b1", "title": "Quiz"}],
+        [existing],
+    )
+    out = remove_block(content, "b2")
+    assert out["suggestions"] == [existing]  # not duplicated
+
+
+def test_prose_cannot_be_removed():
+    content = _content([{"id": "b1", "type": "prose", "text": "intro"}])
+    assert remove_block(content, "b1") is None
+
+
+def test_unknown_block_id_returns_none():
+    content = _content([{"id": "b1", "type": "prose", "text": "intro"}])
+    assert remove_block(content, "nope") is None
+
+
+def test_a_kind_with_no_fallback_brief_is_removed_without_a_restored_suggestion():
+    content = _content([
+        {"id": "b1", "type": "prose", "text": "intro"},
+        {"id": "b2", "type": "table", "after": "b1"},
+    ])
+    out = remove_block(content, "b2")
+    assert out["blocks"] == [{"id": "b1", "type": "prose", "text": "intro"}]
+    assert out["suggestions"] == []
+
+
+def _artifact(content_json: dict, storage_key: str | None = None) -> Artifact:
+    a = Artifact(id=uuid.uuid4(), workspace_id=uuid.uuid4(), type="x", status="ready", content_json=content_json)
+    a.storage_key = storage_key
+    return a
+
+
+def test_copy_block_reuses_a_ready_infographic_by_its_content_not_a_storage_key():
+    # Infographics render from stored HTML (content_json["content"]), never from storage_key: that field is always
+    # None for them. Checking storage_key here used to make every reuse fail with "nothing to add".
+    existing = _artifact({"title": "My infographic", "theme": "midnight", "content": {"title": "t"}}, storage_key=None)
+    block = copy_block("infographic", existing)
+    assert block == {"title": "My infographic", "artifact_id": str(existing.id), "theme": "midnight"}
+
+
+def test_copy_block_rejects_an_infographic_with_no_content():
+    existing = _artifact({"title": "Empty"}, storage_key=None)
+    with pytest.raises(NothingToDo):
+        copy_block("infographic", existing)
+
+
+def test_copy_block_reuses_mind_map_quiz_and_flashcards():
+    assert copy_block("mind_map", _artifact({"title": "Map", "root": {"id": "root"}, "node_count": 3, "post_count": 2})) == \
+        {"title": "Map", "root": {"id": "root"}, "node_count": 3, "post_count": 2}
+    assert copy_block("quiz", _artifact({"title": "Q", "questions": [{"question": "?"}]})) == \
+        {"title": "Q", "questions": [{"question": "?"}]}
+    assert copy_block("flashcards", _artifact({"title": "C", "cards": [{"front": "f", "back": "b"}]})) == \
+        {"title": "C", "cards": [{"front": "f", "back": "b"}]}
+
+
+def test_copy_block_rejects_a_kind_with_nothing_to_reuse():
+    with pytest.raises(NothingToDo):
+        copy_block("quiz", _artifact({"title": "Q", "questions": []}))

backend/tests/test_report_suggestions.py

@@ -0,0 +1,121 @@
+"""The suggested templates in the Create report dialog are written once, kept, prepared in the background and served at once."""
+
+import pytest
+from sqlalchemy import select
+
+from app.config import settings
+from app.llm import run
+from app.models import Job, ReportTemplateCache
+from app.services import report_suggestions
+from tests.test_idea_pool import make_posts, owner  # noqa: F401  (the fixture)
+
+
+@pytest.fixture()
+def asked(monkeypatch):
+    """Fake the model; `asked` lists what it was asked, and `answer` is what it says."""
+    calls: list[list[str]] = []
+    state = {"answer": [{"name": f"Template {n}", "description": "d", "prompt": "Write about {about}."} for n in range(4)]}
+
+    def predict(signature, *, db, workspace_id, job=None, lm=None, **inputs):
+        assert signature.__name__ == "SuggestReportTemplates"
+        calls.append(inputs["items"])
+        return {"templates": state["answer"]}
+
+    monkeypatch.setattr(run, "predict", predict)
+    return calls, state
+
+
+def _suggest(client, headers, docs):
+    return client.post("/api/reports/suggest", json={"document_ids": [str(d.id) for d in docs]}, headers=headers)
+
+
+def test_the_same_sources_get_their_templates_again_without_the_model(client, owner, db_session, asked):  # noqa: F811
+    headers, ws = owner
+    calls, state = asked
+    docs = make_posts(db_session, ws, 4)
+    first = _suggest(client, headers, docs).json()["templates"]
+    again = _suggest(client, headers, list(reversed(docs))).json()["templates"]  # the order they were ticked in does not matter
+    assert len(calls) == 1 and first == again and [t["id"] for t in first] == [f"suggested-{n}" for n in range(1, 5)]
+    assert len(db_session.scalars(select(ReportTemplateCache)).all()) == 1
+    # A post whose ideas changed is a different input: new templates, the old set is left alone
+    docs[0].metadata_json = {**docs[0].metadata_json, "ideas": [{"label": "A new idea", "note": "Changed.", "sources": [], "details": []}]}
+    db_session.commit()
+    _suggest(client, headers, docs)
+    assert len(calls) == 2 and len(db_session.scalars(select(ReportTemplateCache)).all()) == 2
+    # What the model read is the stored ideas, not the post text
+    assert any("- A new idea: Changed." in item for item in calls[1]) and not any("Sentence 1 about" in item for item in calls[1])
+
+
+def test_a_failed_or_empty_answer_is_never_kept(client, owner, db_session, asked):  # noqa: F811
+    headers, ws = owner
+    calls, state = asked
+    docs = make_posts(db_session, ws, 3)
+    state["answer"] = []
+    assert _suggest(client, headers, docs).json() == {"templates": []}
+    state["answer"] = [{"name": "", "description": "", "prompt": ""}, {"name": "Only", "description": "d", "prompt": "p"},
+                       {"name": "only", "description": "dup", "prompt": "p"}]  # a blank and a repeat are dropped
+    assert [t["name"] for t in _suggest(client, headers, docs).json()["templates"]] == ["Only"]
+    assert len(calls) == 2  # the empty answer was not kept, so the next request asked again
+
+
+def test_templates_are_prepared_in_the_background_so_the_dialog_is_instant(client, owner, db_session, run_jobs, asked, monkeypatch):  # noqa: F811
+    headers, ws = owner
+    calls, _ = asked
+    monkeypatch.setattr(settings, "llm_api_key", "test-key")
+    docs = make_posts(db_session, ws, 12, ideas_each=4)
+    client.post("/api/notebooks", json={"title": "Big", "document_ids": [str(d.id) for d in docs]}, headers=headers)
+    client.post("/api/notebooks", json={"title": "Same again", "document_ids": [str(d.id) for d in docs[:3]]}, headers=headers)
+    queued = db_session.scalars(select(Job).where(Job.kind == "report_templates")).all()
+    assert len(queued) == 1  # one at a time, however many notebooks changed
+    assert run_jobs()[0].kind == "report_templates" and len(calls) == 2  # one set written for each notebook
+    ran = len(calls)
+    monkeypatch.setattr(run, "predict", lambda *a, **k: pytest.fail("the dialog's request was prepared already"))
+    r = _suggest(client, headers, docs)  # what the dialog sends: the notebook's posts
+    assert r.status_code == 200 and len(r.json()["templates"]) == 4 and ran == 2
+
+
+def test_warming_skips_posts_whose_ideas_are_not_stored_yet_and_sets_already_kept(db_session, owner, asked):  # noqa: F811
+    _, ws = owner
+    calls, _ = asked
+    from app.models import Notebook, NotebookDocument
+
+    bare = make_posts(db_session, ws, 4, with_ideas=0)
+    nb = Notebook(workspace_id=ws.id, title="Bare")
+    db_session.add(nb)
+    db_session.flush()
+    db_session.add_all([NotebookDocument(notebook_id=nb.id, document_id=d.id) for d in bare])
+    db_session.commit()
+    assert report_suggestions.warm_workspace(db_session, ws.id) == 0 and calls == []  # waits for the ideas
+    for d in bare:
+        d.metadata_json = {"ideas_hash": d.content_hash, "ideas": [{"label": "Idea", "note": "Note.", "sources": [], "details": []}]}
+    db_session.commit()
+    assert report_suggestions.warm_workspace(db_session, ws.id) == 1 and len(calls) == 1
+    assert report_suggestions.warm_workspace(db_session, ws.id) == 0 and len(calls) == 1  # already kept
+
+
+def test_only_one_warm_up_is_queued_and_none_without_a_model_key(db_session, owner, monkeypatch):  # noqa: F811
+    _, ws = owner
+    monkeypatch.setattr(settings, "llm_api_key", "")
+    report_suggestions.queue_warmup(db_session, ws.id)
+    assert db_session.scalars(select(Job).where(Job.kind == "report_templates")).all() == []
+    monkeypatch.setattr(settings, "llm_api_key", "k")
+    report_suggestions.queue_warmup(db_session, ws.id)
+    report_suggestions.queue_warmup(db_session, ws.id)
+    assert len(db_session.scalars(select(Job).where(Job.kind == "report_templates")).all()) == 1
+
+
+def test_unticking_a_post_that_is_not_one_of_the_few_read_gives_the_kept_templates_at_once(client, owner, db_session, asked):  # noqa: F811
+    headers, ws = owner
+    calls, _ = asked
+    docs = make_posts(db_session, ws, 30)
+    everything = _suggest(client, headers, docs).json()["templates"]
+    assert len(calls) == 1
+    read = report_suggestions.stable_order(docs)[: report_suggestions.SUGGEST_ITEMS]
+    others = [d for d in docs if d not in read]
+    for gone in (others[0], others[7], others[-1]):  # the newest, one in the middle, the oldest
+        picked = [d for d in docs if d is not gone]
+        assert _suggest(client, headers, picked).json()["templates"] == everything
+    assert len(calls) == 1  # no new model call: every one of these was a kept set
+    # Unticking one of the few that are read is a different input, and is asked for (and kept) once
+    _suggest(client, headers, [d for d in docs if d is not read[0]])
+    assert len(calls) == 2

backend/tests/test_report_themes.py

@@ -0,0 +1,553 @@
+"""Reports built around themes: the posts' stored ideas are grouped into weighted themes, a blueprint plans the whole report, each
+section is written from its own evidence. The model is always faked here (by signature name, as the other report tests do)."""
+
+import logging
+import uuid
+from types import SimpleNamespace
+
+import pytest
+from sqlalchemy import select
+
+from app.config import settings
+from app.corpus import Corpus
+from app.llm import run
+from app.models import Document, Workspace
+from app.pipeline import report_blueprint, report_evidence, report_themes
+from app.pipeline.generate import ideas_fresh
+from app.pipeline.report_blueprint import Blueprint, Section
+from app.pipeline.report_themes import Idea, Theme, ThemesUnavailable
+from tests.conftest import last_code
+from tests.test_idea_pool import _notebook, make_posts
+
+
+@pytest.fixture()
+def owner(client, db_session):
+    client.post("/api/auth/email/register/start", json={"email": "ada@example.com", "password": "stardust-42", "name": "Ada"})
+    r = client.post("/api/auth/email/register/verify", json={"email": "ada@example.com", "code": last_code()})
+    return {"Authorization": f"Bearer {r.json()['access_token']}"}, db_session.scalar(select(Workspace))
+
+
+def fake_doc() -> SimpleNamespace:
+    return SimpleNamespace(id=uuid.uuid4(), path="sources/x/a.md", title="A")
+
+
+def theme(tid: str, name: str, posts: int, *, asked: bool = False, tier: str = "minor", weight: float = 0.1) -> Theme:
+    t = Theme(id=tid, name=name, summary=f"About {name}.", ideas=[Idea(f"{tid}.{n}", fake_doc(), f"{name} {n}", "n") for n in range(posts)],
+              asked=asked)
+    t.tier, t.weight, t.pinned = tier, weight, asked
+    return t
+
+
+# Weights are counted in code
+
+
+def test_weights_come_from_counting_posts_and_ideas_and_a_priority_theme_moves_up():
+    a, b, c = theme("t1", "A", 8), theme("t2", "B", 4), theme("t3", "C", 1, asked=True)
+    themes = [a, b, c]
+    report_themes.weigh(themes, total_posts=13, total_ideas=13)
+    assert round(sum(t.weight for t in themes), 3) == 1.0
+    assert (a.weight, b.weight, c.weight) == (0.6154, 0.3077, 0.0769)
+    assert (a.tier, b.tier) == ("major", "major")
+    assert c.tier == "medium" and c.pinned  # minor by share, asked for: one tier up and pinned
+
+
+def test_the_heaviest_theme_is_major_even_when_the_weights_are_flat():
+    themes = [theme(f"t{n}", f"T{n}", 3) for n in range(1, 11)]  # ten equal themes: 0.1 each, medium
+    report_themes.weigh(themes, total_posts=30, total_ideas=30)
+    assert sum(t.tier == "major" for t in themes) == 1
+
+
+# Grouping: the model names themes, code files what it left out
+
+
+def _ideas(db_session, ws, n=8):
+    docs = make_posts(db_session, ws, n, ideas_each=2)
+    corpus = Corpus(ws.id)
+    corpus.sync()
+    return docs, report_themes.collect_ideas(docs, corpus)
+
+
+def test_ideas_the_model_left_out_are_filed_by_code_and_the_rest_are_dropped_or_caught(owner, db_session, monkeypatch):
+    _, ws = owner
+    docs, ideas = _ideas(db_session, ws)  # post i has ideas p{i}.0 and p{i}.1; posts cycle Pricing, Growth, Craft
+
+    def predict(sig, *, db, workspace_id, job=None, lm=None, **inputs):
+        assert sig.__name__ == "GroupThemes" and "p0.0 | Pricing idea 0.0:" in inputs["ideas"][0]
+        return {"themes": [
+            {"name": "Pricing", "summary": "s", "matches_request": False,
+             "idea_ids": ["p0.0", "p0.1", "p3.0", "p3.1", "p6.0", "p6.1", "nope"]},
+            {"name": "Audience Growth", "summary": "s", "matches_request": True,
+             "idea_ids": ["p1.0", "p1.1", "p4.0", "p4.1", "p0.0"]},
+            {"name": "", "summary": "no name", "idea_ids": ["p2.0"], "matches_request": False}],
+            "relations": [{"a": "pricing", "b": "Audience Growth", "relation": "Price decides who stays."},
+                          {"a": "Pricing", "b": "Ghost", "relation": "unknown theme"}]}
+
+    monkeypatch.setattr(run, "predict", predict)
+    themes, relations = report_themes.group_themes(db_session, None, ws.id, "Money", "a report", ideas)
+    by_name = {t.name: t for t in themes}
+    assert set(by_name) == {"Pricing", "Audience Growth", report_themes.CATCH_ALL}
+    assert len(by_name["Pricing"].ideas) == 6  # the invented id was dropped
+    assert "p0.0" not in [i.id for i in by_name["Audience Growth"].ideas]  # an idea belongs to one theme only
+    growth = {i.id for i in by_name["Audience Growth"].ideas}
+    assert {"p7.0", "p7.1"} <= growth  # filed by the words it shares with the theme
+    assert {i.doc.path for i in by_name[report_themes.CATCH_ALL].ideas} == {docs[2].path, docs[5].path}  # nothing fits them
+    assert sum(len(t.ideas) for t in themes) == len(ideas)  # every idea counts, so the weights cover all posts
+    assert by_name["Audience Growth"].pinned and [t.id for t in themes] == ["t1", "t2", "t3"]
+    assert relations == [{"a": "t1", "b": "t2", "relation": "Price decides who stays."}]
+
+
+def test_too_few_themes_means_the_posts_are_read_as_before(owner, db_session, monkeypatch):
+    _, ws = owner
+    _, ideas = _ideas(db_session, ws)
+    monkeypatch.setattr(run, "predict", lambda *a, **k: {"themes": [{"name": "Only", "summary": "", "idea_ids": ["p0.0"]}],
+                                                         "relations": []})
+    with pytest.raises(ThemesUnavailable):
+        report_themes.group_themes(db_session, None, ws.id, "Money", "r", ideas)
+
+
+def test_the_model_sees_at_most_300_ideas_one_round_of_every_post_at_a_time(owner, db_session):
+    _, ws = owner
+    docs = make_posts(db_session, ws, 120, ideas_each=8)
+    corpus = Corpus(ws.id)
+    corpus.sync()
+    ideas = report_themes.collect_ideas(docs, corpus)
+    listed = report_themes.listed_ideas(ideas)
+    assert len(ideas) == 960 and len(listed) == report_themes.MAX_LISTED_IDEAS
+    assert len({i.doc.id for i in listed}) == 120  # every post is in the sample
+
+
+def test_a_post_without_ideas_is_represented_by_its_opening(owner, db_session):
+    _, ws = owner
+    docs = make_posts(db_session, ws, 2, with_ideas=0)
+    corpus = Corpus(ws.id)
+    corpus.sync()
+    ideas = report_themes.collect_ideas(docs, corpus)
+    assert [i.bare for i in ideas] == [True, True] and ideas[0].label == docs[0].title
+    assert ideas[0].sources[0]["path"] == docs[0].path and ideas[0].sources[0]["line_start"] >= 1
+
+
+def test_ideas_are_extracted_together_for_at_most_the_inline_limit(owner, db_session, monkeypatch):
+    _, ws = owner
+    docs = make_posts(db_session, ws, 6, with_ideas=0)
+    seen = {}
+
+    def predict_many(sig, inputs_list, *, db, workspace_id, lm=None, workers=5):
+        seen["n"] = len(inputs_list)
+        return [{"ideas": [{"label": "Idea", "note": "n", "details": [],
+                            "sources": [{"path": docs[0].path, "line_start": 7, "line_end": 9}]}]} for _ in inputs_list]
+
+    monkeypatch.setattr(run, "predict_many", predict_many)
+    monkeypatch.setattr(run, "predict", lambda *a, **k: pytest.fail("together, not one by one"))
+    monkeypatch.setattr(settings, "report_inline_ideas", 4)
+    report_themes.ensure_ideas(db_session, None, ws.id, docs)
+    assert seen["n"] == 4 and sum(ideas_fresh(d) for d in docs) == 4
+    assert report_themes.fresh_share(docs) == pytest.approx(4 / 6)
+
+
+# The blueprint is checked against the weights
+
+
+def _bp(*sections: Section, connections=None) -> Blueprint:
+    return Blueprint(title="T", storyline="S", sections=list(sections), connections=connections or [])
+
+
+def _sec(heading, role="body", ids=(), depth="standard", must=()):
+    return Section(heading=heading, role=role, brief=f"{heading} brief", theme_ids=list(ids), depth=depth, must_cover=list(must))
+
+
+def test_the_plan_is_made_to_cover_every_major_and_asked_for_theme_in_its_own_section():
+    themes = [theme("t1", "Pricing", 5, tier="major", weight=0.5), theme("t2", "Hiring", 3, tier="major", weight=0.3),
+              theme("t3", "Tools", 1, weight=0.1), theme("t4", "Remote", 1, asked=True, tier="medium", weight=0.1)]
+    plan = _bp(_sec("Summary", "summary"), _sec("Pricing power", ids=["t1", "t1", "ghost"], depth="brief", must=["a"]),
+               _sec("Also pricing", ids=["t1"]), _sec("Opening", "intro"),
+               connections=[{"theme_ids": ["t1", "t2"], "relation": "linked", "section": "pricing POWER"},
+                            {"theme_ids": ["t1", "zzz"], "relation": "unknown theme", "section": "x"}])
+    fixed = report_blueprint.repair(plan, themes)
+    heads = [s.heading for s in fixed.sections]
+    assert heads == ["Opening", "Pricing power", "Hiring", "Remote", "More to know", "Summary"]  # intro first, summary last
+    by = {s.heading: s for s in fixed.sections}
+    assert by["Pricing power"].theme_ids == ["t1"] and by["Pricing power"].depth == "deep"  # depth follows the weight
+    assert by["Remote"].depth == "deep" and by["More to know"].theme_ids == ["t3"] and by["More to know"].depth == "brief"
+    assert by["Summary"].theme_ids == ["t1", "t2", "t4"] and by["Summary"].depth == "brief"
+    assert "Hiring: About Hiring." in by["Pricing power"].covered_elsewhere
+    assert not any(c.startswith("Pricing power") for c in by["Pricing power"].covered_elsewhere)
+    assert by["Opening"].covered_elsewhere == [] and by["Summary"].covered_elsewhere == []
+    assert fixed.connections == [{"theme_ids": ["t1", "t2"], "relation": "linked", "section": "Pricing power"}]
+
+
+def test_too_many_sections_merge_the_lightest_but_never_a_major_theme():
+    themes = [theme("t1", "Big", 5, tier="major", weight=0.4)] + \
+        [theme(f"t{n}", f"Small {n}", 1, weight=0.05 + n / 1000) for n in range(2, 12)]
+    plan = _bp(_sec("Open", "intro"), _sec("Big one", ids=["t1"]), *[_sec(f"S{n}", ids=[f"t{n}"]) for n in range(2, 12)],
+               _sec("End", "summary"))
+    fixed = report_blueprint.repair(plan, themes)
+    assert len(fixed.sections) == report_blueprint.MAX_SECTIONS
+    assert [s for s in fixed.sections if s.heading == "Big one"][0].theme_ids == ["t1"]
+    assert sorted(i for s in fixed.sections if s.role == "body" for i in s.theme_ids) == sorted(t.id for t in themes)  # none lost
+
+
+def test_a_plan_with_one_section_is_not_usable():
+    with pytest.raises(report_blueprint.BlueprintUnavailable):
+        report_blueprint.repair(_bp(_sec("Only", ids=["t1"])), [theme("t1", "A", 1, tier="major", weight=1.0), ])
+
+
+# The evidence of a section
+
+
+def _themes_from(docs, ideas, groups):
+    """Themes from an index range of posts each, weighed."""
+    themes = [Theme(id=f"t{n}", name=name, summary=f"About {name}.", ideas=[i for i in ideas if lo <= docs.index(i.doc) < hi])
+              for n, (name, lo, hi) in enumerate(groups, start=1)]
+    report_themes.weigh(themes, len(docs), len(ideas))
+    return themes
+
+
+def test_a_deep_section_reads_several_posts_as_written_and_summarises_the_rest(owner, db_session):
+    _, ws = owner
+    docs, ideas = _ideas(db_session, ws, 10)
+    corpus = Corpus(ws.id)
+    t = _themes_from(docs, ideas, [("Everything", 0, 10), ("Other", 0, 0)][:1])
+    sec = _sec("Deep", ids=["t1"], depth="deep")
+    ev = report_evidence.build(corpus, sec, {x.id: x for x in t})
+    raw = [b for b in ev.blocks if b.startswith("POST ")]
+    assert 2 <= len(raw) == ev.raw_posts == 5  # a deep section reads five posts as written, never one
+    assert any(b.startswith("SUMMARIES of other posts") for b in ev.blocks)
+    assert len(ev.posts) == 10  # the other five are represented by their summaries
+    assert "Sentence 1 about" in raw[0] and "[themes: Everything]" in raw[0]  # the post's own words
+    assert "7| " not in raw[0] and "sources/x" not in raw[0]  # nothing is cited, so no line numbers and no paths
+    assert sum(len(b) for b in ev.blocks) <= report_evidence.BUDGETS["deep"]
+
+
+def test_a_brief_section_gets_summaries_only_and_a_standard_one_three_posts(owner, db_session):
+    _, ws = owner
+    docs, ideas = _ideas(db_session, ws, 10)
+    corpus = Corpus(ws.id)
+    t = _themes_from(docs, ideas, [("Everything", 0, 10)])
+    by_id = {x.id: x for x in t}
+    brief = report_evidence.build(corpus, _sec("Brief", ids=["t1"], depth="brief"), by_id)
+    assert brief.raw_posts == 0 and not any(b.startswith("POST ") for b in brief.blocks)
+    assert sum(len(b) for b in brief.blocks) <= report_evidence.BUDGETS["brief"]
+    assert all(' (from "Post ' in line for line in brief.blocks[0].splitlines()[1:])  # each summary says which post it is from
+    standard = report_evidence.build(corpus, _sec("Std", ids=["t1"], depth="standard"), by_id)
+    assert standard.raw_posts == 3
+
+
+def test_a_section_about_two_themes_starts_with_the_posts_that_speak_of_both(owner, db_session):
+    _, ws = owner
+    docs, ideas = _ideas(db_session, ws, 8)
+    corpus = Corpus(ws.id)
+    a, b = Theme("t1", "A", "", []), Theme("t2", "B", "", [])
+    for d in docs:
+        mine = [i for i in ideas if i.doc is d]
+        a.ideas.append(mine[0])
+        if d in docs[5:7]:  # only these two posts have an idea in each theme
+            b.ideas.append(mine[1])
+    report_themes.weigh([a, b], 8, len(ideas))
+    ev = report_evidence.build(corpus, _sec("Bridge", "synthesis", ids=["t1", "t2"], depth="standard"), {"t1": a, "t2": b})
+    first = [b_ for b_ in ev.blocks if b_.startswith("POST ")][:2]
+    assert {docs[5].title, docs[6].title} == {blk.split(" [themes")[0][5:] for blk in first}
+
+
+def test_an_unreadable_post_falls_back_to_its_summary(owner, db_session):
+    _, ws = owner
+    docs, ideas = _ideas(db_session, ws, 6)
+    ideas[0].doc.path = "sources/x/missing.md"
+    corpus = Corpus(ws.id)
+    t = _themes_from(docs, ideas, [("All", 0, 6)])
+    ev = report_evidence.build(corpus, _sec("S", ids=["t1"], depth="deep"), {"t1": t[0]})
+    assert "sources/x/missing.md" in ev.posts and ev.raw_posts == 5  # the five others
+
+
+# The whole report
+
+
+@pytest.fixture()
+def free_to_make(monkeypatch):
+    monkeypatch.setattr("app.routers.artifacts.check_limit", lambda *a, **k: None)
+
+
+class Fake:
+    """The model, by signature name. `calls` is every call in order; `sections` the inputs of every WriteThemedSection."""
+
+    def __init__(self, monkeypatch, docs, groups, ask=None, fail=(), quiz_themes=()):
+        self.docs, self.calls, self.sections, self.fail = docs, [], [], set(fail)
+        self.quiz_themes = list(quiz_themes)
+        self.groups, self.ask, self.plan_inputs, self.report_inputs = groups, ask, None, None
+        monkeypatch.setattr(run, "predict", self.predict)
+        monkeypatch.setattr(run, "predict_many", self.predict_many)
+
+    def predict(self, sig, *, db, workspace_id, job=None, lm=None, **inputs):
+        name = sig.__name__
+        self.calls.append(name)
+        if name == "GroupThemes":
+            ids = [line.split(" | ")[0] for line in inputs["ideas"]]
+            out = []
+            for title, lo, hi in self.groups:
+                mine = [i for i in ids if lo <= int(i[1:].split(".")[0]) < hi]
+                out.append({"name": title, "summary": f"About {title}.", "idea_ids": mine, "matches_request": title == self.ask})
+            rel = [{"a": self.groups[0][0], "b": self.groups[1][0], "relation": "One shapes the other."}] if len(self.groups) > 1 else []
+            return {"themes": out, "relations": rel}
+        if name == "PlanReportBlueprint":
+            self.plan_inputs = inputs
+            return {"report_title": "Pricing and growth", "storyline": "Prices set expectations and growth follows.", "sections": [
+                {"heading": "Why this matters", "role": "intro", "brief": "Opens.", "theme_ids": [], "depth": "brief",
+                 "must_cover": ["scope"]},
+                {"heading": "Pricing power", "role": "body", "brief": "Pricing.", "theme_ids": ["t1"], "depth": "deep",
+                 "must_cover": ["raise slowly"],
+                 "embed": {"kind": "flashcards", "title": "Terms", "brief": "Price terms", "why": "Learn them"}},
+                {"heading": "Audience growth", "role": "body", "brief": "Growth.", "theme_ids": ["t2"], "depth": "standard",
+                 "must_cover": ["retention"]},
+                {"heading": "Quick quiz", "role": "body", "brief": "Test it.", "theme_ids": self.quiz_themes, "depth": "brief",
+                 "must_cover": []},
+                {"heading": "Wrap up", "role": "summary", "brief": "Closes.", "theme_ids": [], "depth": "brief",
+                 "must_cover": ["main points"]}],
+                "connections": [{"theme_ids": ["t1", "t2"], "relation": "Price shapes who stays.",
+                                 "section": "Audience growth"}]}
+        if name == "WriteThemedReport":
+            self.report_inputs = inputs
+            text = "## Why this matters\nIntro [1].\n\n## Pricing power\nBody [2].\n\n## Wrap up\nEnd."
+            return {"report_title": "One Piece", "markdown": text}
+        if name == "WriteReport":
+            return {"report_title": "Legacy", "markdown": "## One\nText."}
+        raise AssertionError(f"unexpected {name}")
+
+    def predict_many(self, sig, inputs_list, *, db, workspace_id, lm=None, workers=5):
+        assert sig.__name__ == "WriteThemedSection"
+        out = []
+        for inp in inputs_list:
+            self.sections.append(inp)
+            self.calls.append("WriteThemedSection")
+            if inp["heading"] in self.fail:
+                out.append(None)
+            else:
+                out.append({"markdown": f"{inp['heading']} text [1]."})  # a marker the model wrote anyway
+        return out
+
+
+def _report(client, owner, docs, fmt, **extra):
+    headers, _ = owner
+    nb = _notebook(client, owner, docs)
+    return client.post("/api/artifacts/generate", json={
+        "type": "report", "notebook_id": nb["id"], "document_ids": [str(d.id) for d in docs], "report_format": fmt,
+        "instructions": "Write a report.", **extra}, headers=headers).json()
+
+
+def _content(client, owner, art):
+    return client.get(f"/api/artifacts/{art['id']}", headers=owner[0]).json()["content"]
+
+
+GROUPS = [("Pricing", 0, 6), ("Audience Growth", 6, 8), ("Writing Craft", 8, 10)]  # 60%, 20%, 20% of the posts
+
+
+def test_an_interactive_report_is_planned_then_written_section_by_section_from_its_own_evidence(client, owner, db_session, run_jobs,
+                                                                                               monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    fake = Fake(monkeypatch, docs, GROUPS, quiz_themes=["t3"])  # the plan wrongly makes a section of a quiz
+    art = _report(client, owner, docs, "interactive")
+    run_jobs()
+    c = _content(client, owner, art)
+    assert c["format"] == "interactive" and c["plan"]["planner"] == "themes"
+    assert [b["text"].split("\n")[0] for b in c["blocks"]] == [
+        "## Why this matters", "## Pricing power", "## Audience growth", "## Wrap up"]
+    assert "PlanInteractiveReport" not in fake.calls and "WriteReportSection" not in fake.calls and "WriteReport" not in fake.calls
+    assert fake.calls[:2] == ["GroupThemes", "PlanReportBlueprint"]
+    # The weights are counted: Pricing is in six of ten posts
+    themes = {t["name"]: t for t in c["plan"]["themes"]}
+    assert themes["Pricing"]["tier"] == "major" and themes["Pricing"]["weight"] == 0.6 and themes["Audience Growth"]["tier"] == "medium"
+    assert c["plan"]["posts_total"] == 10 and c["source"]["total"] == 10 and len(c["source"]["document_ids"]) == 10
+    # Nothing is cited. The Sources list is every post the report was made from, shown in a drop-down with the prompt
+    assert c["citations"] == [] and not any("[" in b["text"] for b in c["blocks"])
+    assert c["source"]["read"] == c["plan"]["posts_used"] == len(c["sources"]) == 10
+    assert {x["document_id"] for x in c["sources"]} == {str(d.id) for d in docs} and all("markers" not in x for x in c["sources"])
+    assert c["instructions"] == "Write a report."
+    # The planner saw the allowed visuals and the themes, never the posts
+    assert fake.plan_inputs["allowed_kinds"] and all("POST" not in line for line in fake.plan_inputs["themes"])
+    # Body sections first, then the introduction and the summary, written from what the sections say
+    written = [s["heading"] for s in fake.sections]
+    assert written[:2] == ["Pricing power", "Audience growth"] and written[2:] == ["Why this matters", "Wrap up"]
+    pricing = fake.sections[0]
+    assert pricing["storyline"].startswith("Prices set") and len(pricing["outline"]) == 4
+    assert pricing["covered_elsewhere"][0].startswith("Audience growth:")
+    assert all(not x.startswith("Pricing power") for x in pricing["covered_elsewhere"])
+    assert sum(e.startswith("POST ") for e in pricing["evidence"]) >= 2  # several posts as written
+    growth = fake.sections[1]
+    assert growth["bridges"] == ["Pricing + Audience Growth: Price shapes who stays. (bridged in: Audience growth)"]
+    assert fake.sections[2]["evidence"][0].startswith("Pricing power: Pricing power text") and fake.sections[2]["role"] == "intro"
+    assert "Restate the main points about: Pricing" in fake.sections[3]["must_cover"][-1]
+    assert growth["evidence"] and "Writing Craft" in growth["evidence"][-1]  # the quiz section's theme stayed in the report
+    # Visuals are only suggested; the quiz section became a suggestion
+    # The plan suggested no infographic, so one is offered after the last section before the summary
+    assert [(s["after_block_id"], s["kind"]) for s in c["suggestions"]] == [
+        ("b2", "flashcards"), ("b3", "quiz"), ("b3", "infographic")]
+    assert "failed_sections" not in c
+
+
+def test_a_document_report_is_written_in_one_piece_from_the_plan_and_offers_no_visuals(client, owner, db_session, run_jobs,
+                                                                                      monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    fake = Fake(monkeypatch, docs, GROUPS)
+    art = _report(client, owner, docs, "document")
+    run_jobs()
+    c = _content(client, owner, art)
+    assert c["format"] == "document" and c["plan"]["planner"] == "themes"
+    assert c["suggestions"] == []  # never in a document
+    assert fake.calls == ["GroupThemes", "PlanReportBlueprint", "WriteThemedReport"]
+    assert fake.plan_inputs["allowed_kinds"] == []
+    sections = fake.report_inputs["sections"]
+    assert sections[0].startswith("SECTION 1: Why this matters") and all(s.startswith("SECTION") for s in sections)
+    assert "Evidence:\nPOST " in sections[1] and fake.report_inputs["storyline"].startswith("Prices set")
+    assert [b["text"].split("\n")[0] for b in c["blocks"]] == ["## Why this matters", "## Pricing power", "## Wrap up"]
+    assert c["citations"] == [] and not any("[" in b["text"] for b in c["blocks"]) and len(c["sources"]) == 10
+    assert sum(len(s) for s in sections) < report_evidence.BUDGETS["deep"] * 4  # the evidence fits its budget
+
+
+def test_more_than_twenty_posts_are_all_used(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 30, ideas_each=2)
+    fake = Fake(monkeypatch, docs, [("Pricing", 0, 20), ("Audience Growth", 20, 25), ("Writing Craft", 25, 30)])
+    art = _report(client, owner, docs, "interactive")
+    run_jobs()
+    c = _content(client, owner, art)
+    assert c["plan"]["posts_total"] == 30 and len(c["source"]["document_ids"]) == 30
+    assert {t["name"]: t["posts"] for t in c["plan"]["themes"]} == {"Pricing": 20, "Audience Growth": 5, "Writing Craft": 5}
+    assert fake.calls[0] == "GroupThemes"
+
+
+def test_a_theme_the_reader_asked_for_gets_its_own_deep_section(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    Fake(monkeypatch, docs, GROUPS, ask="Writing Craft")
+    art = _report(client, owner, docs, "interactive", instructions="Focus on writing craft.")
+    run_jobs()
+    c = _content(client, owner, art)
+    sections = {s["heading"]: s for s in c["plan"]["sections"]}
+    assert sections["Writing Craft"]["depth"] == "deep" and sections["Writing Craft"]["theme_ids"] == ["t3"]
+    assert {t["name"]: t["pinned"] for t in c["plan"]["themes"]}["Writing Craft"] is True
+
+
+def test_a_section_that_fails_is_tried_again_then_reported_not_hidden(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    seen: list[str] = []
+
+    class Flaky(Fake):
+        def predict_many(self, sig, inputs_list, **kw):
+            seen.extend(i["heading"] for i in inputs_list)
+            return super().predict_many(sig, inputs_list, **kw)
+
+    Flaky(monkeypatch, docs, GROUPS, fail=["Audience growth"])
+    art = _report(client, owner, docs, "interactive")
+    run_jobs()
+    c = _content(client, owner, art)
+    assert seen.count("Audience growth") == 2  # once, then once more
+    assert c["failed_sections"] == ["Audience growth"]
+    assert [b["text"].split("\n")[0] for b in c["blocks"]] == ["## Why this matters", "## Pricing power", "## More to know", "## Wrap up"]
+
+
+def test_when_the_ideas_cannot_be_themed_the_posts_are_read_as_before(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    fake = Fake(monkeypatch, docs, [("Only", 0, 10)])  # a single theme is no plan
+    art = _report(client, owner, docs, "document")
+    run_jobs()
+    c = _content(client, owner, art)
+    assert fake.calls == ["GroupThemes", "WriteReport"] and "plan" not in c and c["title"] == "Legacy"
+
+
+def test_small_selections_chats_and_the_legacy_setting_keep_the_old_way(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    fake = Fake(monkeypatch, docs, GROUPS)
+    small = _report(client, owner, docs[:5], "document")  # five posts or fewer: read whole
+    run_jobs()
+    assert fake.calls == ["WriteReport"] and "plan" not in _content(client, owner, small)
+    fake.calls.clear()
+    monkeypatch.setattr(settings, "report_planner", "legacy")
+    _report(client, owner, docs, "document")
+    run_jobs()
+    assert fake.calls == ["WriteReport"]
+
+
+def test_posts_without_ideas_use_the_old_way_until_half_have_them(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    docs = make_posts(db_session, owner[1], 10, with_ideas=3, ideas_each=2)
+    monkeypatch.setattr(settings, "report_inline_ideas", 0)  # nothing is extracted while the report is made
+    fake = Fake(monkeypatch, docs, GROUPS)
+    _report(client, owner, docs, "document")
+    run_jobs()
+    assert fake.calls == ["WriteReport"]
+    assert [d for d in db_session.scalars(select(Document)) if ideas_fresh(d)].__len__() == 3
+
+
+def test_every_step_of_a_themed_report_is_logged(client, owner, db_session, run_jobs, monkeypatch, free_to_make, caplog):
+    caplog.set_level(logging.INFO, logger="app")
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    Fake(monkeypatch, docs, GROUPS)
+    _report(client, owner, docs, "interactive")
+    run_jobs()
+    text = "\n".join(r.getMessage() for r in caplog.records)
+    for expected in ("report posts: ", "themed report starting: ", "report ideas collected: ", "report themes: asking the model",
+                     "report theme: id=t1 name='Pricing' weight=0.600 tier=major", "report blueprint checked: ",
+                     "report section 1: heading='Why this matters'", "report evidence: section='Pricing power' depth=deep",
+                     "report wave 1: ", "report wave 2: ", "report interactive written: ", "themed report done: ",
+                     "report: job="):
+        assert expected in text, expected
+    assert "way=themes" in text
+
+
+def test_a_fallback_says_why(client, owner, db_session, run_jobs, monkeypatch, free_to_make, caplog):
+    caplog.set_level(logging.INFO, logger="app")
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    Fake(monkeypatch, docs, [("Only", 0, 10)])
+    _report(client, owner, docs, "document")
+    run_jobs()
+    text = "\n".join(r.getMessage() for r in caplog.records)
+    assert "report themes unusable: usable=1 needed=2" in text and "reading the posts instead" in text and "way=legacy" in text
+    caplog.clear()
+    _report(client, owner, docs[:5], "document")
+    run_jobs()
+    assert "report route: legacy" in "\n".join(r.getMessage() for r in caplog.records)
+
+
+def test_a_report_always_offers_visuals_and_never_repeats_what_the_plan_suggested():
+    from app.pipeline import report
+
+    blocks = [{"id": f"b{n}", "type": "prose"} for n in range(1, 6)]
+    kinds = list(report.EMBED_KINDS)
+    nothing = report.fill_suggestions([], blocks, kinds)
+    assert [(s["kind"], s["after_block_id"]) for s in nothing] == [("infographic", "b4"), ("flashcards", "b2"), ("quiz", "b3")]
+    planned = [{"id": "s1", "after_block_id": "b1", "kind": "infographic", "brief": "x", "why": "y"}]
+    kept = report.fill_suggestions(planned, blocks, kinds)
+    assert kept[0] == planned[0] and [s["kind"] for s in kept] == ["infographic", "flashcards", "quiz"]  # not offered twice
+    assert [s["kind"] for s in report.fill_suggestions([], blocks, ["infographic", "mind_map"])] == ["infographic", "mind_map"]
+    assert report.fill_suggestions([], blocks, []) == [] and report.fill_suggestions([], [], kinds) == []
+    chat = report.fill_suggestions([], blocks, [k for k in kinds if k != "mind_map"])
+    assert "mind_map" not in {s["kind"] for s in chat}
+
+
+def test_an_older_report_without_suggestions_gets_them_once_when_opened(client, owner, db_session, run_jobs, monkeypatch, free_to_make):
+    from app.models import Artifact
+
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    Fake(monkeypatch, docs, GROUPS)
+    art = _report(client, owner, docs, "interactive")
+    run_jobs()
+    row = db_session.get(Artifact, uuid.UUID(art["id"]))
+    row.content_json = {k: v for k, v in row.content_json.items() if k not in ("suggestions", "suggestions_offered")}  # as an old one
+    db_session.commit()
+    first = _content(client, owner, art)
+    assert {"infographic", "flashcards", "quiz"} <= {s["kind"] for s in first["suggestions"]} and first["suggestions_offered"]
+    # Once: a reader who has added or taken everything away is not offered them again
+    row = db_session.get(Artifact, uuid.UUID(art["id"]))
+    db_session.refresh(row)
+    row.content_json = {**row.content_json, "suggestions": []}
+    db_session.commit()
+    assert _content(client, owner, art)["suggestions"] == []
+
+
+def test_a_document_report_is_never_given_suggestions_not_even_an_old_one_when_opened(client, owner, db_session, run_jobs, monkeypatch,
+                                                                                     free_to_make):
+    from app.models import Artifact
+
+    docs = make_posts(db_session, owner[1], 10, ideas_each=2)
+    Fake(monkeypatch, docs, GROUPS)
+    art = _report(client, owner, docs, "document")
+    run_jobs()
+    row = db_session.get(Artifact, uuid.UUID(art["id"]))
+    row.content_json = {k: v for k, v in row.content_json.items() if k not in ("suggestions", "suggestions_offered")}
+    db_session.commit()
+    assert _content(client, owner, art).get("suggestions", []) == []

frontend/src/components/ArtifactFeedback.tsx

@@ -0,0 +1,145 @@
+import { useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
+import { artifactsApi } from "../api/endpoints";
+import type { AnswerFeedback as Feedback, Artifact } from "../api/types";
+import { Thumb } from "./AnswerFeedback";
+import { errorMessage } from "./ui";
+
+/** What can be rated: finished reports, quizzes, flashcard sets and infographics. */
+export const RATEABLE = ["report", "quiz", "flashcards", "infographic"];
+
+/** Why a thumbs down, per kind (the ids the server keeps; see services/artifact_feedback.py). */
+const REASONS: Record<string, { id: string; label: string }[]> = {
+  report: [
+    { id: "inaccurate", label: "Inaccurate or made up" },
+    { id: "missed_points", label: "Missed key points" },
+    { id: "structure", label: "Poorly structured" },
+    { id: "tone", label: "Wrong tone or style" },
+    { id: "too_long", label: "Too long" },
+    { id: "too_short", label: "Too short" },
+    { id: "other", label: "Something else" },
+  ],
+  quiz: [
+    { id: "wrong_answers", label: "Wrong answers" },
+    { id: "too_easy", label: "Too easy" },
+    { id: "too_hard", label: "Too hard" },
+    { id: "unclear", label: "Unclear questions" },
+    { id: "off_topic", label: "Not from my material" },
+    { id: "other", label: "Something else" },
+  ],
+  flashcards: [
+    { id: "inaccurate", label: "Inaccurate" },
+    { id: "too_basic", label: "Too basic" },
+    { id: "too_detailed", label: "Too detailed" },
+    { id: "unclear", label: "Unclear wording" },
+    { id: "other", label: "Something else" },
+  ],
+  infographic: [
+    { id: "messy_layout", label: "Messy layout" },
+    { id: "cut_off", label: "Text cut off or overlapping" },
+    { id: "missing_content", label: "Wrong or missing content" },
+    { id: "look", label: "The look does not suit" },
+    { id: "hard_to_read", label: "Hard to read" },
+    { id: "other", label: "Something else" },
+  ],
+};
+
+// A rating is shown wherever its artifact is (the card, the viewer, the results), so they share one copy.
+const ratings = new Map<string, Feedback | null>();
+const listeners = new Set<() => void>();
+const subscribe = (fn: () => void) => {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+};
+function put(id: string, fb: Feedback | null) {
+  ratings.set(id, fb);
+  listeners.forEach((l) => l());
+}
+
+/** Thumbs up and thumbs down on a generated report, quiz, flashcard set or infographic, so it is clear which ones are
+ * good. A thumbs down asks why (optional). Saved as soon as it is chosen; shared by every place the artifact shows.
+ * `compact` opens the reasons over the page instead of pushing it down. */
+export function ArtifactFeedback({ artifact, label, compact = false }: { artifact: Artifact; label?: ReactNode; compact?: boolean }) {
+  const initial = artifact.feedback ?? null;
+  const fb = useSyncExternalStore(subscribe, () => (ratings.has(artifact.id) ? ratings.get(artifact.id)! : initial), () => initial);
+  const [open, setOpen] = useState(false);
+  const [reasons, setReasons] = useState<string[]>(initial?.reasons ?? []);
+  const [comment, setComment] = useState(initial?.comment ?? "");
+  const [error, setError] = useState<string | null>(null);
+  const [thanks, setThanks] = useState(false);
+  const options = REASONS[artifact.type] ?? [];
+  const whyRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (open) whyRef.current?.scrollIntoView({ block: "nearest", behavior: "smooth" }); // in a fixed size popup it can open below the fold
+  }, [open, fb?.rating]);
+  if (!RATEABLE.includes(artifact.type) || artifact.status !== "ready") return null;
+
+  const save = async (rating: "up" | "down" | null, r: string[] = [], c = "") => {
+    const before = fb;
+    setError(null);
+    put(artifact.id, rating ? { rating, reasons: r, comment: c || null } : null); // shows at once; undone if the save fails
+    try {
+      const res = await artifactsApi.rate(artifact.id, { rating, reasons: r, comment: c || undefined });
+      put(artifact.id, res.feedback);
+    } catch (e) {
+      put(artifact.id, before);
+      setError(errorMessage(e));
+    }
+  };
+
+  const choose = (rating: "up" | "down") => {
+    setThanks(false);
+    if (fb?.rating === rating) {
+      setOpen(false);
+      void save(null);
+      return;
+    }
+    setOpen(true); // both ratings can take a few words (a thumbs down also asks why)
+    if (rating === "up") {
+      setReasons([]);
+      setComment("");
+    }
+    void save(rating, rating === "down" ? reasons : []);
+  };
+
+  return (
+    <div className={`fb afb${compact ? " afb-compact" : ""}`}>
+      <div className="fb-row">
+        {label && <span className="muted small afb-label">{label}</span>}
+        <button type="button" className={`fb-btn${fb?.rating === "up" ? " is-on" : ""}`} aria-pressed={fb?.rating === "up"}
+                aria-label="Good" title="Good" onClick={() => choose("up")}>
+          <Thumb />
+        </button>
+        <button type="button" className={`fb-btn${fb?.rating === "down" ? " is-on is-down" : ""}`} aria-pressed={fb?.rating === "down"}
+                aria-label="Not good" title="Not good" onClick={() => choose("down")}>
+          <Thumb down />
+        </button>
+        {thanks && <span className="mono muted small">Thanks, saved.</span>}
+        {error && <span className="error-text small">Could not save that. Try again.</span>}
+      </div>
+      {open && fb && (
+        <div className="fb-why afb-why" ref={whyRef}>
+          <p className="mono muted small">{fb.rating === "up" ? "What worked well? (optional)" : "What was wrong? (optional)"}</p>
+          {fb.rating === "down" && <div className="fb-chips">
+            {options.map((r) => (
+              <button key={r.id} type="button" className={`fb-chip${reasons.includes(r.id) ? " is-on" : ""}`} aria-pressed={reasons.includes(r.id)}
+                      onClick={() => setReasons((list) => (list.includes(r.id) ? list.filter((x) => x !== r.id) : [...list, r.id]))}>
+                {r.label}
+              </button>
+            ))}
+          </div>}
+          <textarea className="input fb-note" rows={2} maxLength={1000} value={comment} onChange={(e) => setComment(e.target.value)}
+                    placeholder={fb.rating === "up" ? "Tell us more, like what you liked" : "Tell us more, like what it should have been"}
+                    aria-label={fb.rating === "up" ? "What worked well" : "What was wrong"} />
+          <div className="row end">
+            <button type="button" className="btn btn-small" onClick={() => setOpen(false)}>Skip</button>
+            <button type="button" className="btn btn-small btn-primary" onClick={async () => {
+              await save(fb.rating, fb.rating === "down" ? reasons : [], comment.trim());
+              setOpen(false);
+              setThanks(true);
+            }}>Send</button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/hooks/reportSuggestions.ts

@@ -0,0 +1,24 @@
+import { reportsApi } from "../api/endpoints";
+import type { ReportTemplate } from "../api/types";
+
+/** The suggested report templates for some sources. The server keeps them (prepared as soon as ideas are extracted), so a repeat is
+ * instant; this also shares one request between the notebook page asking early and the dialog asking when it opens. */
+const asked = new Map<string, Promise<ReportTemplate[]>>();
+
+export function suggestTemplates(body: Record<string, unknown>): Promise<ReportTemplate[]> {
+  const key = JSON.stringify(body);
+  let found = asked.get(key);
+  if (!found) {
+    found = reportsApi.suggest(body).then((r) => r.templates).catch((e) => {
+      asked.delete(key); // a failure is tried again next time
+      throw e;
+    });
+    asked.set(key, found);
+  }
+  return found;
+}
+
+/** Ask for a notebook's templates ahead of time, for the posts the Create report dialog starts with ticked, so they are ready when it opens. */
+export function prefetchSuggestions(notebookId: string, postIds: string[]) {
+  if (postIds.length) suggestTemplates({ document_ids: postIds, notebook_id: notebookId }).catch(() => undefined);
+}

frontend/src/hooks/useArtifactLimits.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from "react";
+import { settingsApi } from "../api/endpoints";
+
+/** Posts a report or infographic reads, and a dialog ticks to start with (the server's ARTIFACT_MAX_POSTS; this is the default until it
+ * answers). A quiz or flashcard set can pick as many as the plan indexes (`selectable`). */
+export type ArtifactLimits = { posts: number; selectable: number };
+
+const DEFAULTS: ArtifactLimits = { posts: 20, selectable: 20 };
+let known: ArtifactLimits | null = null;
+let asked: Promise<ArtifactLimits> | null = null;
+const listeners = new Set<(l: ArtifactLimits) => void>();
+
+/** Ask the server once; everyone shares the answer. */
+export function loadArtifactLimits(): Promise<ArtifactLimits> {
+  if (!asked) {
+    asked = settingsApi.limits().then((r) => {
+      known = { posts: r.posts, selectable: r.selectable_posts };
+      listeners.forEach((fn) => fn(known!));
+      return known;
+    }).catch(() => {
+      asked = null; // try again next time
+      return known ?? DEFAULTS;
+    });
+  }
+  return asked;
+}
+
+export function useArtifactLimits(): ArtifactLimits {
+  const [limits, setLimits] = useState<ArtifactLimits>(known ?? DEFAULTS);
+  useEffect(() => {
+    listeners.add(setLimits);
+    void loadArtifactLimits();
+    return () => {
+      listeners.delete(setLimits);
+    };
+  }, []);
+  return limits;
+}