thursday-agent 0.9.0 → 0.11.0

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

@@ -0,0 +1,60 @@
+---
+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. The chart script ships with the app:
+
+```bash
+C="$THURSDAY_SKILLS/interactive-page/scripts/chart.mjs"
+node $C "$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 $C "$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 $C` 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.

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

@@ -0,0 +1,51 @@
+# Where the numbers are
+
+Take a figure from whoever publishes it, not from an article quoting it. When two sources
+disagree, the order of trust is: a filing or an official statistic; the company's own release or
+call; an industry body's report; a research firm's estimate; news.
+
+## What `fetch.mjs` reaches (no key)
+
+| Source | For | Command |
+|---|---|---|
+| FRED | US economy, rates, markets; many OECD and BIS series for other countries | `fred <ID,…>` |
+| World Bank | Every country, yearly: GDP, population, inflation, trade | `worldbank <ISO2,…> <INDICATOR>` |
+| Yahoo Finance | Stocks, ETFs, indices, crypto, futures; any exchange | `yahoo <TICKER,…> [--interval 1d\|1wk\|1mo]` |
+| ECB reference rates | Exchange rates, about 30 currencies, since 1999 | `fx <BASE> <QUOTE,…>` |
+| SEC XBRL | US-listed companies' reported figures, yearly or quarterly | `sec <TICKER> --find <word>`, then `sec <TICKER> <CONCEPT,…>` |
+| Wikipedia pageviews | Public interest in a topic, monthly (a stand-in for search trends) | `pageviews <ARTICLE,…> [--wiki ko]` |
+
+Ids worth knowing, all checked to be current:
+
+- FRED, US: `CPIAUCSL` consumer prices, `UNRATE` unemployment, `FEDFUNDS` policy rate, `DGS10`
+  10-year Treasury, `MORTGAGE30US` 30-year mortgage, `SP500`, `NASDAQCOM`, `DCOILWTICO` oil.
+- FRED, Korea: `IRSTCI01KRM156N` overnight rate, `IRLTLT01KRM156N` 10-year bond,
+  `LRHUTTTTKRM156S` unemployment, `DEXKOUS` won per dollar (daily), `QSKR628BIS` house prices.
+  Korea's monthly consumer prices are no longer on FRED; the yearly rate is World Bank
+  `FP.CPI.TOTL.ZG`, the monthly index is on the Bank of Korea and KOSIS sites.
+- World Bank: `NY.GDP.MKTP.CD` GDP in dollars, `NY.GDP.MKTP.KD.ZG` real growth, `NY.GDP.PCAP.CD`
+  GDP per person, `SP.POP.TOTL` population, `FP.CPI.TOTL.ZG` inflation.
+- Yahoo tickers: Korean listings end in `.KS` (KOSPI) or `.KQ` (KOSDAQ), Tokyo `.T`, Hong Kong
+  `.HK`; indices start with `^` (`^GSPC`, `^IXIC`, `^KS11`, `^N225`); `BTC-USD`; `KRW=X` is won per
+  dollar.
+- SEC concepts: revenue is `Revenues` for some companies and
+  `RevenueFromContractWithCustomerExcludingAssessedTax` for others, and a company can switch —
+  `--find` shows which one it uses now. Others: `OperatingIncomeLoss`, `NetIncomeLoss`,
+  `EarningsPerShareDiluted`, `Assets`, `StockholdersEquity`. A fourth quarter is not filed on its
+  own; the script works it out as the year less three quarters and says so in the file.
+
+## What it does not reach
+
+- **Korean official statistics** — the Bank of Korea (ECOS) and KOSIS APIs, and company filings
+  through OpenDART, need a free key the user signs up for. Without one, read the table on the
+  site (ecos.bok.or.kr, kosis.kr, dart.fss.or.kr) and write the rows into a CSV with a `# source:`
+  line.
+- **Prices in shops, rents, listings** — pages, not APIs: open them in the browser, one listing at
+  a time, and record each with its link and the time you saw it.
+- **Search trends** — Google Trends has no open API; Wikipedia pageviews or a site's own published
+  counts stand in, and say that they do.
+- **Market-size totals** — research firms publish the headline figure in a press release and sell
+  the rest. Take the headline with its year and what it counts; never the paywalled detail
+  quoted secondhand.
+
+A source that does not answer twice in a row is down, not empty: say so and use another.

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

@@ -0,0 +1,39 @@
+# Trend
+
+How something moved and what moved it: the series itself, from its source, with the events
+that explain its turns marked on it.
+
+## Collect
+
+- The series from the publisher (`fetch.mjs`, or a table on its site), over a window at least
+  three times as long as the period asked about, so "recently" can be seen against normal.
+- A comparison series when it tells the story: the same measure elsewhere, the thing it is
+  usually compared with (rent against pay, a stock against its index). Different units:
+  `--index`.
+- For each turn the text explains, a dated event from a source: a rate decision, a policy, a
+  launch, a shock. A turn with no sourced cause is said to be unexplained.
+
+## Final text
+
+The level now and its date; the change over the period asked about, as a number and a percent;
+the one or two things that moved it. Missing or revised points are said.
+
+## Page
+
+1. Title: the movement as a finding. Lede: level now, change, main cause.
+2. The line chart, with a `--mark` for each event the text names.
+3. A small table: now, one year ago, three or five years ago, the high and low with dates.
+4. What moved it, one short paragraph per mark, each with its source.
+5. What to watch: the next release date, and the level that would change the story.
+
+## Example (illustrative numbers)
+
+> **Mortgage rates fell a full point in a year, following the 10-year bond**
+>
+> The 30-year rate is 6.1% (2026-09-17), down from 7.1% a year earlier; the 10-year Treasury
+> fell from 4.6% to 3.9% over the same weeks.
+>
+> [chart: both lines since 2020, marks at the first rate cut and the jobs report that followed]
+>
+> Watch: the next inflation release on 10-14; a monthly core reading above 0.3% has pushed the
+> 10-year up each time this year.