thursday-agent 0.8.0 → 0.10.0

package/features/workspace/components/artifact-view.tsx

@@ -11,12 +11,21 @@ import { markSeenAction } from "@/features/bot/bot.action";
 import type { Bot } from "@/features/bot/bot.schema";
 import { shortenPaths } from "@/features/bot/components/attachments";
 import { BotMark } from "@/features/bot/components/bot-mark";
-import { roomOpens, useBotThreads } from "@/features/bot/thread.store";
+import {
+  roomOpens,
+  type ThreadView,
+  useBotThreads,
+} from "@/features/bot/thread.store";
 import { FileThumb } from "@/features/workspace/components/file-thumb";
-import { viewKindOf } from "@/features/workspace/file-kind";
+import {
+  opensOnFinish,
+  pathsIn,
+  viewKindOf,
+} from "@/features/workspace/file-kind";
+import { toDate } from "@/lib/date-like";
 import { unwrapResult } from "@/lib/protocol/result";
 import { revalidate, useServerRoute } from "@/lib/protocol/use-server-route";
-import { errorToString } from "@/lib/utils";
+import { errorToString, plainText } from "@/lib/utils";
 import { FileViewer, useOpenFile } from "./file-view";
 
 /**
@@ -52,6 +61,86 @@ export type Finished = {
 /** File faces a card draws before the rest fold into a count. */
 const FACES_SHOWN = 4;
 
+/**
+ * Cards waved off in this browser, newest first, so a reload does not bring them back. Short:
+ * a card also goes once its thread is read, which the server keeps.
+ */
+const DISMISSED_KEY = "thursday.corner-dismissed";
+const DISMISSED_KEEP = 50;
+
+function readDismissed(): string[] {
+  try {
+    const stored = JSON.parse(
+      window.localStorage.getItem(DISMISSED_KEY) ?? "[]",
+    );
+    return Array.isArray(stored) ? stored : [];
+  } catch {
+    return [];
+  }
+}
+
+function rememberDismissed(ids: string[]) {
+  try {
+    const kept = [
+      ...ids,
+      ...readDismissed().filter((id) => !ids.includes(id)),
+    ].slice(0, DISMISSED_KEEP);
+    window.localStorage.setItem(DISMISSED_KEY, JSON.stringify(kept));
+  } catch {
+    // blocked storage: the card comes back after a reload, which is only a card
+  }
+}
+
+/**
+ * A job finished while this page is not the one in front: the browser's own notification,
+ * which brings Thursday forward when pressed — the card is waiting there. Nothing when the
+ * page is in front (the card says it) or notifications were never allowed (see
+ * `askToNotify`).
+ */
+function tellFinished(threadId: string, label: string, words: string) {
+  if (typeof Notification === "undefined") return;
+  if (Notification.permission !== "granted") return;
+  if (document.visibilityState === "visible" && document.hasFocus()) return;
+  try {
+    const shown = new Notification(label, {
+      body: words,
+      tag: threadId,
+      icon: "/icon.svg",
+    });
+    shown.onclick = () => {
+      window.focus();
+      shown.close();
+    };
+  } catch {
+    // a browser that shows none from a page; the card and the room still have it
+  }
+}
+
+/**
+ * Asks once, in the browser's quiet way, whether this page may show a notification when a
+ * job finishes out of sight. Called as a call is placed: the moment someone starts handing
+ * out work, and never on load.
+ */
+export function askToNotify() {
+  if (typeof Notification === "undefined") return;
+  if (Notification.permission !== "default") return;
+  void Notification.requestPermission().catch(() => undefined);
+}
+
+/** A finished job as a card, read off its row when no event brought it: after a reload. */
+function cardOf(thread: ThreadView): Finished {
+  const files = pathsIn(thread.outcome ?? "");
+  const lead = files.findIndex(opensOnFinish);
+  return {
+    threadId: thread.id,
+    label: thread.label,
+    bot: thread.bot.name,
+    words: plainText(thread.outcome ?? "").slice(0, FINISHED_NOTICE.words),
+    paths:
+      lead > 0 ? [files[lead], ...files.filter((_, at) => at !== lead)] : files,
+  };
+}
+
 function Notice() {
   const [rows, setRows] = useState<Finished[]>([]);
   const { data: bots } = useServerRoute<Bot[]>(queryKey.bot);
@@ -66,7 +155,8 @@ function Notice() {
         event.paths[0],
         event.paths.filter((path) => viewKindOf(path) === "image"),
       ),
-    finished: (event) =>
+    finished: (event) => {
+      tellFinished(event.threadId, event.label, event.words);
       setRows((was) =>
         [
           {
@@ -79,11 +169,40 @@ function Notice() {
           // A job that finishes twice (picked back up, ended again) keeps one card
           ...was.filter((row) => row.threadId !== event.threadId),
         ].slice(0, FINISHED_NOTICE.rows),
-      ),
+      );
+    },
   });
 
-  const drop = (threadId: string) =>
+  // What finished while the page was away, or before a reload, and is still unread: the
+  // corner holds it until it is opened or waved off, as an event would have put it there
+  const seeded = useRef(false);
+  useEffect(() => {
+    if (seeded.current || !threads.length) return;
+    seeded.current = true;
+    const dismissed = new Set(readDismissed());
+    const waiting = threads
+      .filter(
+        (thread) =>
+          thread.status === "done" && !thread.seen && !dismissed.has(thread.id),
+      )
+      .sort(
+        (a, b) => toDate(b.updatedAt).getTime() - toDate(a.updatedAt).getTime(),
+      );
+    if (!waiting.length) return;
+    setRows((was) =>
+      [
+        ...was,
+        ...waiting
+          .filter((thread) => !was.some((row) => row.threadId === thread.id))
+          .map(cardOf),
+      ].slice(0, FINISHED_NOTICE.rows),
+    );
+  }, [threads]);
+
+  const drop = (threadId: string) => {
+    rememberDismissed([threadId]);
     setRows((was) => was.filter((row) => row.threadId !== threadId));
+  };
 
   // Read somewhere else (the room, `thread_show`): the card goes. A card is armed
   // only once its thread was seen unread, since the thread list may still hold
@@ -147,7 +266,10 @@ function Notice() {
           <span className="flex-1">{rows.length} new</span>
           <button
             type="button"
-            onClick={() => setRows([])}
+            onClick={() => {
+              rememberDismissed(rows.map((row) => row.threadId));
+              setRows([]);
+            }}
             className="rounded-md px-1 font-sans text-[11px] outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50"
           >
             Clear all

package/guide/bots.md

@@ -67,7 +67,7 @@ clear later why the bot changed course. Saying the same to her on a call does th
 A job ends in the thing that was asked for and a short report. Anything longer than a few
 lines is a file. Nothing opens by itself: every finished job waits as a card in the corner at
 the bottom left of the call screen — the bot, the job's name, how its answer begins, and its
-files under that — until it is opened or dismissed. Opening a card, or a file on it, counts as
+files under that — until it is opened or dismissed, a reload of the page included. Opening a card, or a file on it, counts as
 reading the result: the thread stops showing as new, and she will not bring it up on a call.
 Dismissing a card does not; the result still waits in its thread. The files also show under
 the bot's words in the thread: pictures as thumbnails, a page or a written report as a small preview
@@ -80,10 +80,22 @@ folder, listed on its page in Settings › Bots.
 
 ## Routines: jobs that start by themselves
 
-A routine is a bot, a job and a time: every weekday at nine, every six hours. It is made by
-telling Thursday — "every morning at nine, go through my mail" — or in **Settings ›
-Routines**, which lists them all, each with one switch. There are two kinds of time, a time of
-day on chosen days, or every so many hours, and at most twelve routines.
+A routine is a bot, a job and a time: tomorrow at eight, every weekday at nine, every six
+hours. It is made by telling Thursday — "every morning at nine, go through my mail", "in an
+hour, check the fares again" — or in **Settings › Routines**, which lists them all, each with
+one switch. **When** has three kinds of time, and at most twelve routines exist:
+
+- **Once**: a day (today, tomorrow, the two days after, or any day from the calendar) and a
+  time, or **In an hour**. It starts that once and then switches itself off; it stays in the
+  list with its run, and picking a new day and time sets it again. A time already gone is
+  refused.
+- **On set days**: a time of day on the days picked. Every day, Weekdays and Weekends fill the
+  days in one press.
+- **Every few hours**: 1, 2, 3, 6, 12 or 24 hours after each start; any other number can be
+  asked of Thursday.
+
+What is picked is filled blue, and the line under the field says it back in words, with when
+it first starts.
 
 Each time it is due, a routine opens an ordinary thread, marked with a repeat sign, and that
 thread behaves like any other: it shows in the corner of the call screen, a question pauses

package/guide/calls.md

@@ -74,10 +74,13 @@ keeps them under the search.
 ## Hearing the words
 
 **Settings › Thursday › Captions** picks where the words show: under her face, or down the
-two sides of the screen. What she is doing — a search, work handed to a bot, what she is
-thinking about — shows as one line under her face; with the words down the sides it stands on
-her side instead, under what she last said, the last three steps at a time with the older
-ones fainter. Every call is kept; **Settings › Thursday › History** opens them,
+two sides of the screen. A narrow window always shows them under her face. What she is
+doing — a search, work handed to a bot — shows as one line under her face; with the words down
+the sides it stands on her side instead, under what she said, the last three steps at a time
+with the older ones fainter, and the steps stay with that answer for the rest of the call:
+clicking an earlier answer of hers brings it back with the steps behind it. What she is
+thinking about stays under her face either way. Every call is kept; **Settings › Thursday ›
+History** opens them,
 one call at a time, and deletes a single call or all of them.
 
 ## Her voice, her face, her models
@@ -98,13 +101,18 @@ one call at a time, and deletes a single call or all of them.
 While a call is open, a question or a result from a bot comes into the conversation by
 itself, in a quiet moment, and she says it.
 
-With no call open, the computer shows a notification. **Settings › Thursday › Starting a
+With no call open, a finished job lands as a card in the bottom left corner, and if Thursday
+is not the window in front, as a notification that brings her forward when pressed (the
+browser asks once, the first time a call is placed). With no Thursday window open at all,
+the computer's own notification says it instead; on a Mac pressing that one opens Script
+Editor rather than the app. **Settings › Thursday › Starting a
 call › She calls you** makes the screen ring instead: "When a job needs me" rings for a
 question or a stop — where it starts — "Whenever a job ends" rings for results too, and
 "Never" leaves it to the notification. It is one call however much is waiting: while it rings, the screen says under her
 face whose work it is about and what it asks — with the answers the bot offered, and the
-other work waiting by name — and one round button, Answer. Tapping her face answers too, Esc
-is "not now", and she opens by saying why she called, then tells the rest one by one. A ring
+other work waiting by name — and one round button, Answer. Tapping her face answers too, and
+so does the wake phrase when it is on (the screen says so beside "not now"); Esc is "not now".
+She opens by saying why she called, then tells the rest one by one. A ring
 nobody takes becomes a short missed list in the same place, with Call back, until it is
 called back or cleared with Esc; the work itself stays in the room either way. She cannot
 switch this on herself: when they ask to be

package/guide/setup.md

@@ -37,7 +37,8 @@ Settings › Thursday instead.
 
 A skill is a written-down way of doing something that a bot reads before it starts. Some ship
 with the app — the browser, this Mac, finding more skills, building a page or a chart, and
-writing a new skill. **Settings › Skills** lists them, switches one off, uploads one, or
+writing a new skill. The one for this Mac is not listed on other computers.
+**Settings › Skills** lists them, switches one off, uploads one, or
 writes one. A bot can also install one from the open registry while it works: for itself
 alone unless they asked for every bot to have it. A bot's own skills sit in its own folder
 and are not on that screen, which lists the shared ones.
@@ -49,6 +50,12 @@ details. Once connected, its tools are there for bots to search and call, and up
 them can be pinned to one bot so they are always in front of it. Signing in happens in a
 popup window; a server that needs it again turns red on that screen.
 
+The list starts with everyday services — to-dos, the house, flights, and Zapier for Gmail,
+Google Calendar and the other apps connected there — and the tools for developers come after.
+Home Assistant is the one that asks for two things first: the address of their own Home
+Assistant, and a long-lived access token made on their profile page there. Its Model Context
+Protocol Server integration has to be added in Home Assistant too.
+
 ## Sites they signed in to
 
 When a bot needs them signed in to a website — to post, to read mail, to order — it opens a
@@ -77,7 +84,8 @@ of the Settings list for as long as it is not installed. Safari on a Mac does it
 its File menu, **Add to Dock**; Firefox cannot. It is the same local app either way; nothing
 moves anywhere.
 
-The app comes back on the same address every time it starts. If that port is taken by
+The app comes back on the same address every time it starts: the first start takes port 4747,
+which other apps rarely use, and keeps it. If that port is taken by
 something else one day, it says so where it was started and serves on the next one for that
 day; the browser then shows other settings, because a browser keeps settings per address.
 Starting it once with `--port` and a number moves it to that address for good.

package/knip.json

@@ -3,6 +3,7 @@
   "entry": ["scripts/intro-voice.mts", ".agents/skills/*/*.cjs"],
   "ignore": [
     "skills/**",
+    "seed-skills/**",
     "components/ui/**",
     ".agents/skills/!(verify|cleanup|checkup)/**"
   ],

package/lib/desktop-notify.ts

@@ -2,8 +2,9 @@ import { execFile } from "node:child_process";
 import { APP_NAME } from "@/config";
 
 /**
- * Native desktop notification for work that finished while nobody is on the
- * line. Best effort: the inbox is the durable signal, so failures are swallowed.
+ * Native desktop notification for work that finished while no page is open (with one open,
+ * the page shows its own). Best effort: the inbox is the durable signal, so failures are
+ * swallowed. On macOS it is AppleScript's, so pressing it opens Script Editor, not the app.
  */
 
 /** The OS truncates longer text anyway. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thursday-agent",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "A voice agent that runs on your own machine — talk to her, she hands the slow work to bots with a shell, a browser and skills.",
   "license": "MIT",
   "keywords": [

package/scripts/bot-context.test.mts

@@ -1326,7 +1326,7 @@ test("the call makes, reads and removes a routine, and is told when its time can
     String(
       await routine({ action: "create", ...job, time: "09:00", everyHours: 6 }),
     ),
-    /not both/,
+    /Give one of `at`, `time` or `everyHours`/,
   );
   assert.match(
     String(

package/seed-skills/analyst/README.md

@@ -0,0 +1,19 @@
+# Analyst's kit
+
+One skill the Analyst seed is born with, copied into `.agents/skills/` in its own folder when it is
+created. It is listed to that bot alone.
+
+| Skill | What it adds |
+|---|---|
+| `data-report` | Seven report forms, each with its structure and a filled example; `fetch.mjs`, which pulls a published series (FRED, World Bank, Yahoo Finance, ECB rates, SEC filings, Wikipedia pageviews) into a CSV that names its source; `chart.mjs`, which draws a CSV into a quick page as a cited figure |
+
+Written for this app. The forms borrow their shape from answer-first business writing and from the
+report outlines in [anthropics/financial-services](https://github.com/anthropics/financial-services)
+and [anthropics/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
+(Apache-2.0); no text is copied from either. Those skills write Word, PowerPoint and Excel files and
+read paid data connectors, which is why they are not taken whole.
+
+`chart.mjs` fills a page made by the shipped `interactive-page` skill's quick path and uses its
+colour tokens; it draws inline SVG, so the page still opens with no network. The scripts need Node
+and no packages. Every source they call answers without a key; `references/sources.md` names the
+ones that need one.

package/seed-skills/analyst/data-report/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: data-report
+description: "Answers and reports built on real numbers: the form each kind of question wants (a brief, a comparison with a pick, a market size, a trend, a company snapshot, a price check, a buy-or-wait decision), scripts that fetch a published series into CSV with its source, and one that draws a CSV into a page as a cited chart."
+---
+
+# Data report
+
+## The form comes from the question
+
+Pick one form and read only its file in `references/` before collecting anything: it says what to
+collect, what the final text holds, and when a page earns its place.
+
+| The question | Form |
+|---|---|
+| Anything else with numbers in it | `brief.md` |
+| Which of these (products, plans, places, companies)? | `comparison.md` |
+| How big is this market, how much could we sell? | `market-size.md` |
+| How has X moved, and why? | `trend.md` |
+| How is this company doing, how were its results? | `company.md` |
+| Where is it cheapest to buy X right now? | `price-check.md` |
+| Should I buy / sign / switch — or wait? | `decision.md` |
+
+Every form opens with the answer and its two or three numbers; a reader who stops after the first
+lines has what they asked for. A title says the finding ("Rent rose faster than pay"), not the topic.
+
+## Numbers by script, not by hand
+
+The skill's scripts are in `scripts/` of this skill's folder. `node` runs them; nothing to install.
+
+```bash
+S=<this skill's folder>/scripts
+# A series into CSV, with its source written into the file. It prints the rows' shape and both ends.
+node $S/fetch.mjs fred DGS10,MORTGAGE30US --from 2020 --out <scratch>/rates.csv
+node $S/fetch.mjs yahoo 005930.KS,^KS11 --from 2025-01 --interval 1wk --label Samsung,KOSPI --out <scratch>/px.csv
+```
+
+`references/sources.md` says which source holds what, the series ids worth knowing, and what the
+scripts cannot reach. A CSV you build from a page or a file you were given takes the same shape: a
+`# source: <url>` line (and `# fetched: YYYY-MM-DD`) above a header row.
+
+## A page: the quick page, with charts drawn into it
+
+When the form calls for a page, start it as a quick page from your Skills list (one styled HTML file
+in your folder under `artifacts/`) and write its words by hand. It arrives styled: replace the title
+and the lede line and write below them, and leave its `<head>` as it is. Never write chart SVG or a
+data table by hand: leave an empty `<figure id="…"></figure>` where each chart goes, then fill every
+one in one bash call.
+
+```bash
+node $S/chart.mjs "$THURSDAY_ARTIFACTS/<page>.html" rates <scratch>/rates.csv \
+  --title "Mortgage rates followed the 10-year down" --unit "%" --mark "2024-09=First Fed cut" --locale ko
+node $S/chart.mjs "$THURSDAY_ARTIFACTS/<page>.html" px <scratch>/px.csv --index --title "…"
+```
+
+Each figure carries its source link, the fetch date and the rows behind it with a CSV download, so
+the page needs no separate data section. A line for dates, bars for categories (largest first,
+`--highlight` the one that matters); `--index` when series in different units are compared;
+`--mark` for each dated event the text explains. Run it again to replace a figure.
+`node $S/chart.mjs` with no arguments lists every option.

package/seed-skills/analyst/data-report/references/brief.md

@@ -0,0 +1,31 @@
+# Brief
+
+The default form: a question with numbers in it that no other form fits. Most answers end here,
+as final text, with no page.
+
+## Collect
+
+The one to three figures that answer the question, each from the page or file that publishes it,
+with that page's date. A figure you work out (a share, a change, a per-person cost) shows its
+arithmetic in one line.
+
+## Final text
+
+1. The answer in one sentence, carrying its number.
+2. Up to three lines, one reason each, each with its figure and source.
+3. What is not solid: an estimate, a source older than the question, two sources that disagree
+   (give both).
+
+A page is worth making only when the reasons need a chart or a table longer than five rows; then
+the page is these same lines on top, the chart or table under them.
+
+## Example (illustrative numbers)
+
+> Q: How much has the price of a subway ride gone up in this city?
+>
+> Up 39% in ten years: ₩1,050 in 2015 to ₩1,450 now (city transit site, fares page, 2026).
+> - The last rise was ₩1,250 → ₩1,400 in 2023, then ₩1,550 planned for next year was cut to
+>   ₩1,450 (city press release, 2025-06).
+> - Consumer prices rose 24% over the same years (national statistics office CPI, 2015 = 100 → 124),
+>   so the fare grew faster than prices.
+> - Not solid: the planned rise for next year is a proposal, not a decision.

package/seed-skills/analyst/data-report/references/company.md

@@ -0,0 +1,41 @@
+# Company snapshot
+
+How a company is doing, or how its latest results went, in the terms investors and employees use.
+
+## Collect
+
+- The latest quarter and the same quarter a year earlier: revenue, operating income, net income,
+  margin; the full-year figures for context. From the company's own filing or results release —
+  a US filer through `fetch.mjs sec`, a Korean one from its DART filing or IR page.
+- What management said it expects next (guidance), in their words, with the date.
+- Consensus estimates, only from a page that shows them, with that page's name and date; the
+  beat or miss is actual against that.
+- The share price reaction: `fetch.mjs yahoo`, the close before the release against the close
+  after, and against the market index over the same days.
+- Valuation when asked: price ÷ earnings per share over the last four quarters, with both inputs.
+
+## Final text
+
+The headline in one sentence (grew or shrank, by how much, beat or missed), the one number
+behind the reaction, and what to watch next quarter.
+
+## Page
+
+1. Title: the result as a finding. Lede: the headline and its cause.
+2. A results table: this quarter, a year ago, change; estimates beside it when you have them.
+3. Revenue and operating income by quarter, two years (`--quarterly`), as a line or bars.
+4. The price around the release against the index (`--index`), marked at the release.
+5. Three things to watch, each with the level that would matter.
+
+## Example (illustrative numbers)
+
+> **Northwind grew 18% but guided below what the market expected**
+>
+> | (₩ billion) | Q2 2026 | Q2 2025 | Change |
+> |---|---|---|---|
+> | Revenue | 1,240 | 1,051 | +18% |
+> | Operating income | 161 | 147 | +10% |
+> | Operating margin | 13.0% | 14.0% | −1.0 pt |
+>
+> Shares fell 6.2% the day after (index −0.4%): Q3 revenue guidance of ₩1,260–1,290 billion sat
+> under the ₩1,330 billion consensus (brokerage summary on a finance portal, 2026-07-28).

package/seed-skills/analyst/data-report/references/comparison.md

@@ -0,0 +1,42 @@
+# Comparison with a pick
+
+Options side by side — products, plans, cities, schools, companies — ending in one pick for what
+the user said matters.
+
+## Collect
+
+- The options: the ones the user named, exactly those. Asked to choose them, three to five that a
+  person shopping today would really consider, and say why those.
+- The criteria: what the user said matters first, then what decides this kind of choice (price
+  over the time it is owned, not only the sticker; the spec people regret skipping).
+- Every cell from a page you opened, all on the same basis: the same period, the same definition,
+  one currency (say the exchange rate and its date). A cell you could not fill is "—" with the
+  reason in a note, never blank and never a guess.
+
+## Final text
+
+The pick and the one number that decides it, then the runner-up and when it wins instead
+("Take B; if you fly more than twice a year, A pays for itself"). The page's path.
+
+## Page
+
+1. Title: the pick as a finding. Lede: the pick, its deciding number, and who should choose
+   otherwise.
+2. The matrix: options as columns (or rows, when there are more than four), criteria as rows,
+   units in the row label, the best cell in each row marked, the pick's column marked. A photo
+   of each option when people choose it partly by how it looks.
+3. One bar chart for the criterion that decides it (`--highlight` the pick).
+4. Per option, two lines: what it is best at, what it gives up.
+5. Sources and the date checked.
+
+## Example (illustrative numbers)
+
+> **Plan B costs the least for a family of four** — ₩118,000 a month against ₩131,000 and ₩146,000.
+>
+> | | Plan A | **Plan B** | Plan C |
+> |---|---|---|---|
+> | Monthly, 4 lines (₩) | 131,000 | **118,000** | 146,000 |
+> | Data per line (GB) | 30 | 25 | **unlimited** |
+> | Contract (months) | 24 | **none** | 24 |
+>
+> Plan C wins only if two or more of you use more than 25 GB most months.

package/seed-skills/analyst/data-report/references/decision.md

@@ -0,0 +1,28 @@
+# Buy, sign, switch — or wait
+
+A yes or no the user has to make, answered with the numbers it turns on.
+
+## Collect
+
+- The full cost of each path over the time it runs: price, running costs, what is lost by
+  leaving (a penalty, a resale value), what the money would earn otherwise.
+- The break-even: the point (months, uses, a price, a rate) where the answer flips.
+- What is known about the future that bears on it, from a source: a model launch date, a
+  scheduled rate decision, a seasonal sale, a published price increase.
+
+## Final text
+
+The verdict first — **Yes**, **No**, or **Wait until <when or what>** — with the number that
+decides it, then the condition that would flip it. No verdict without a number under it.
+
+## Page
+
+Only when the costs need a table: each path's costs over time, the break-even as a line chart
+(both paths' cumulative cost, crossing at the break-even), then what would change the verdict.
+
+## Example (illustrative numbers)
+
+> **Wait until November.** The current model costs ₩1,390,000; its successor is announced for
+> 10-28 (maker's event page), and the current model dropped 18% within six weeks of the last
+> launch (comparison site's price history, 2025). Buy now only if you need it before November:
+> waiting is worth about ₩250,000.

package/seed-skills/analyst/data-report/references/market-size.md

@@ -0,0 +1,49 @@
+# Market size
+
+How big a market is and how much of it is reachable: TAM, SAM, SOM, each with its arithmetic in
+the open, so a reader can change one input and see the rest move.
+
+## Collect
+
+- A published total, when one exists: who measured it, for which year, what it counts (sales or
+  spending, which countries, which products). Two publishers usually disagree; take both.
+- Bottom-up inputs, each with its source: how many buyers (a census, a registry, a company's
+  own count), what share of them buy, how often, at what price.
+- Growth: the series itself (`fetch.mjs`), or the publisher's rate with its years.
+
+## The arithmetic
+
+Build it both ways and show both:
+
+- **Top-down**: published total × the share that fits the question (region, segment) = SAM.
+- **Bottom-up**: buyers × share who buy × purchases a year × price = SAM.
+
+Each is a table of drivers, one row each: the value, its unit, its source. The result is a range
+(low and high inputs), never one point. When the two ways differ by more than about 2×, say which
+input is most likely wrong. SOM is SAM × a share you state and justify (what the leader holds,
+what a new entrant took in its first years), never a share picked to look good.
+
+## Final text
+
+SAM as a range in one currency and year, the SOM that follows from the share you assumed, and the
+input the answer depends on most.
+
+## Page
+
+Title: the size as a finding. Then the two driver tables, a bar chart of TAM / SAM / SOM, the
+growth series as a line when there is one, and the assumptions the user may want to change.
+
+## Example (illustrative numbers)
+
+> **Home coffee subscriptions here: ₩180–260 billion a year (2025)**
+>
+> | Bottom-up driver | Value | Source |
+> |---|---|---|
+> | Households | 22.3 M | Statistics office, 2025 |
+> | Buy beans online at least monthly | 4–6% | Industry survey, 2024 (n = 3,000) |
+> | Orders a year | 10 | same survey |
+> | Average order | ₩19,000 | median of 12 shops' listings, checked 2026-09 |
+> | **SAM** | **₩170–255 billion** | 22.3 M × 4–6% × 10 × ₩19,000 |
+>
+> Top-down: ₩1.9 trillion coffee retail (market report, 2025) × 12% online bean share = ₩228 billion.
+> SOM at 2% of SAM (what the third-largest shop holds): ₩3.4–5.1 billion.

package/seed-skills/analyst/data-report/references/price-check.md

@@ -0,0 +1,33 @@
+# Price check
+
+Where one exact thing is cheapest to buy right now, and whether now is a good time.
+
+## Collect
+
+- The exact item: model number, size, color, condition (new, refurbished, used). Two listings of
+  "the same" thing often differ here; a cheaper one that is not the same item is left out or
+  said to differ.
+- From each seller: the price the user pays at the door — item, shipping, tax or duty, any fee —
+  delivery date, return terms, and the listing's link. Open each listing; a search result's price
+  is often stale.
+- Price history when a price tracker or comparison site shows it: the lowest and usual price over
+  months, so "cheapest now" can be told from "cheap".
+- Imports: duty and tax at the user's border, and the exchange rate with its date.
+
+## Final text
+
+Where to buy and the total paid, how much it saves against the next best, and whether the price
+is low, usual or high against its recent history. The time you checked.
+
+## Page
+
+Only when there are more than about five sellers or the history matters: a table sorted by total
+paid (the pick marked), a bar chart of totals (`--highlight` the pick), the history as a line when
+there is one.
+
+## Example (illustrative numbers)
+
+> Cheapest now: Shop B, ₩389,000 delivered by Friday — ₩24,000 under the next best (Shop A,
+> ₩413,000 with ₩3,000 shipping). The lowest in the last six months was ₩372,000 (a comparison
+> site's history, 2026-05); ₩389,000 is near the low end of its usual ₩385,000–420,000.
+> Checked 2026-09-19 14:10.