create-pmos 0.239.0 → 0.241.0

package/workspace/c3-report-structure-test.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+'use strict';
+/* c3-report-structure-test.js — the Structure step of the report studio, UI slice (initiative report-structure; mockup 43-reportstructure;
+ * API contract planning/prd/report-structure-contract.md). A real server and a real Chromium drive /c3.html?tab=rep; the routes of the
+ * contract (/api/report-structure*, /api/charts) and the report reads are answered by Playwright route interception, so the page is
+ * tested against the contract alone, not against the backend (c3-report-structure-real-test.js does that).
+ *
+ *   entry      the Ask PMOS answer (Shape it with PMOS sets the report up, then opens Structure), a set-up row (Shape the report, before Design
+ *              how it looks) and the step bar of the Design studio (1 Structure, 2 Design)
+ *   turn       a first turn shows PMOS working, lands S1 with its questions as answer chips; a chip fills the box; a refine turn lands S2; the
+ *              strip lists both; S1 can be shown again and Go back to S1 posts a revert
+ *   plan       What it answers; Sources in From PMOS and Outside PMOS with their state tags and actions (Open, Test pull, Check it works, How to
+ *              connect); Charts tagged New chart / From Charts; a row opens to question, Used in, what PMOS reads, why and the test pull;
+ *              Outline with chart chips and PMOS notes
+ *   chart      Discuss this chart fills the box; Remove it posts a remove and lands the next version
+ *   source     Add a source offers every From PMOS and Outside PMOS kind; a From PMOS source and a Chrome source are added; the Chrome check
+ *              shows its steps with Needs you and Check again, and passes on the second check
+ *   options    Other structures: three side by side, the recommended first
+ *   dry        Try it with real data runs one job and shows headline, values, flags, could not get, options
+ *   accept     Use this structure posts the shown version; the setup sheet shows the saved structure with Refine the structure
+ *   charts     the Charts tab lists a data chart beside the built-ins with its source and Used in
+ *   phone      at 400 wide none of it scrolls sideways
+ * Set RX_SHOTS=<dir> to save screenshots at 1440 and 400 wide. No script error and no failed request may be raised. */
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { findBrowser } = require('./lib/find-browser');
+const T = require('./test-run').configure({ name: 'c3-report-structure' });
+
+const BASE = T.BASE;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const until = async (fn, ms = 10000, step = 100) => { const t0 = Date.now(); for (;;) { const v = await fn(); if (v) return v; if (Date.now() - t0 > ms) return v; await sleep(step); } };
+const results = [];
+const ok = (name, cond, extra = '') => { results.push({ name, cond: !!cond }); console.log(`${cond ? '✓' : '✗'} ${name}${!cond && extra !== '' ? ' — ' + String(extra).slice(0, 400) : ''}`); };
+let srv = null; let browser = null;
+const finish = async (code) => {
+  if (browser) await browser.close().catch(() => {});
+  if (srv) { try { srv.kill('SIGKILL'); } catch { /* gone */ } }
+  T.killTmux();
+  const bad = results.filter((x) => !x.cond).length;
+  console.log(`\n${results.length - bad}/${results.length} c3-report-structure assertions passed`);
+  process.exit(code !== undefined ? code : (bad ? 1 : 0));
+};
+process.on('unhandledRejection', (e) => { console.error(e); finish(1); });
+
+/* ── the stub: the contract's routes, as a small state machine ── */
+const SETUP = { id: 'app-monthly', name: 'MySPH app performance, monthly', source: 'work', output: 'doc', status: 'active', schedule: { cadence: 'monthly', dayOfMonth: 3, time: '09:00' }, label: 'Monthly on the 3rd 09:00, draft only', next_draft: '2026-11-03', last_issued: null, cycles: 0, copy: null };
+const PROPOSAL = { name: 'MySPH app performance, monthly', purpose: 'Where to invest next quarter.', audience: 'Leadership', source: 'work', output: 'doc', schedule: { cadence: 'monthly', dayOfMonth: 3, time: '09:00' }, sources: ['Google Analytics'], sections: ['Headline'], learned_from: null, fixes: [] };
+const src = (id, kind, name, o) => ({ id, kind, name, via: '', ref: '', use: '', state: 'reached', group: ['connector', 'link', 'upload', 'person', 'chrome', 'computer'].includes(kind) ? 'outside' : 'pmos', ...o });
+const GA = src('ga', 'connector', 'Google Analytics 4: MySPH web + app', { via: 'Read through your Supermetrics connector', use: 'Test pull Mon 12 Oct 22:31. App streams iOS and Android, Sep 2026.' });
+const BOARD = src('board', 'pmos-level', 'Board: MySPH', { via: 'What the report covers', use: 'Its initiatives, releases, key results and risks.' });
+const DASH = src('dash', 'dashboard', 'Dashboard: MySPH health', { via: '2 of its 6 charts used', use: 'New users is already a chart there.' });
+const PAST = src('past', 'past-report', 'Past report: none yet', { via: 'From the second cycle', use: 'From November, PMOS reads the October report.', state: 'later' });
+const BQ = src('bq', 'connector', 'BigQuery: GA4 export', { via: 'Not connected', use: 'Optional. Only needed for retention older than 14 months.', state: 'not-connected' });
+const CH_NEW = { id: 'cpa', chart: null, name: 'Cost per new user', source: 'ga', from: 'GA4 cost', how: 'Paid spend divided by new users from paid campaigns', compare: 'Previous month', flag: 'Up 15% or more', question: 'What do new users cost us?', query: 'GA4 Data API: metric advertiserAdCost; filter sessionMedium = cpc', why: 'Spend explains the drop in new users.' };
+const CH_OLD = { id: 'new-users', chart: 'new-users', name: 'New users', source: 'ga', from: 'GA4 newUsers', how: 'Month total, app streams only', compare: 'Previous month', flag: 'Down 10% or more', question: 'Are we still bringing people in?', query: 'GA4 Data API: metric newUsers', why: 'The top of the funnel.' };
+const CH_RET = { id: 'ret', chart: null, name: 'D30 retention', source: 'ga', from: 'GA4 cohort exploration', how: 'Share of each monthly cohort still active on day 30', compare: 'The last 3 cohorts', flag: 'Below 25%', question: 'Do they stay?', query: 'GA4 Data API runReport with cohortSpec', why: 'You asked for it in S2.' };
+const SEC = (id, title, o) => ({ id, title, fixed: false, charts: [], notes: '', show: '', ...o });
+const OPTIONS = [
+  { name: 'Goals first', sections: ['Headline', 'One block per Q4 objective', 'Where to invest'], good: 'A team that reviews against OKRs.', misses: 'Numbers outside an OKR disappear.', recommended: false },
+  { name: 'Funnel first', sections: ['Headline', 'New users, activation, subscriptions', 'Where to invest'], good: 'Leadership deciding where to invest.', misses: 'Less detail per feature.', recommended: true },
+  { name: 'Features first', sections: ['Headline', 'One block per feature', 'What to build next'], good: 'A product team deciding what to fix next.', misses: 'Leadership has to add the money side.', recommended: false },
+];
+const plan1 = () => ({ purpose: { readers: 'Leadership: Gita Rahma and the product directors', decision: 'Where to invest next quarter', scope: 'MySPH app, iOS and Android', cadence: 'monthly', questions: ['Where do users drop between installing and paying?', 'What should we fund next quarter?'] },
+  sources: [BOARD, DASH, PAST, GA, BQ].map((s) => ({ ...s })), charts: [CH_OLD, CH_NEW].map((c) => ({ ...c })),
+  outline: [SEC('headline', 'Headline', { fixed: true, notes: 'The one thing leadership must know this month', show: 'Two sentences' }), SEC('funnel', 'The funnel this month', { charts: ['new-users', 'cpa'], notes: 'Where do users drop?', show: 'Funnel chart' }),
+    SEC('needs', 'Needs your call', { fixed: true, notes: 'Asks to leadership' }), SEC('sources', 'Sources', { fixed: true, notes: 'Sources reached and not reached' })], options: OPTIONS });
+const Q1 = [{ q: 'Who reads it, and what do they decide with it?', chips: ['Leadership: where to invest next quarter', 'Product team: what to fix next', 'Both'] }, { q: 'Anything that must be in it?', chips: ['Revenue', 'Releases this month', 'Nothing more'] }];
+
+function makeStub() {
+  const S = { versions: [], plans: {}, log: [], current: null, saved: null, running: null, ticks: 0, dry: null, dryResult: null, checks: {}, posts: [], gets: [], chartsRead: 0, polls: 0, setupMade: 0, designStep: 0 };
+  const now = () => '2026-10-12T22:' + String(10 + S.versions.length * 3 + S.log.length).padStart(2, '0') + ':00.000Z';
+  const land = (turn, plan, answer, extra) => { const n = S.versions.length + 1; S.versions.push({ n, at: now(), turn }); S.plans[n] = plan; S.current = n; S.log.push({ who: 'pmos', text: answer, at: now(), n, questions: [], options: [], ...(extra || {}) }); };
+  const view = () => {
+    if (S.running) { S.ticks++; if (S.ticks >= 2) { const r = S.running; S.running = null; r.done(); } }
+    return { ok: true, setup: { id: SETUP.id, name: SETUP.name, cadence: 'monthly' }, structure: { running: !!S.running, job: S.running ? { kind: S.running.kind } : null, current: S.current, saved: S.saved, versions: S.versions.slice(), log: S.log.slice(),
+      plan: S.current ? S.plans[S.current] : null, dry: S.dry, checks: S.checks, errors: [] } };
+  };
+  const chromeChecks = (pass) => ({ source: 'looker', kind: 'chrome', at: now(), running: false, ok: pass, steps: [
+    { id: 'mac', label: 'PMOS runs on this Mac', state: 'works', reason: 'The read runs on your MacBook.' }, { id: 'session', label: 'A session can start with Claude in Chrome', state: 'works', reason: 'PMOS started a test session.' },
+    { id: 'extension', label: 'Claude in Chrome answers', state: 'works', reason: 'The extension answered.' },
+    { id: 'signed-in', label: 'You are signed in to Looker Studio', state: pass ? 'works' : 'needs-you', reason: pass ? 'Opened the report as you.' : 'Chrome showed the Google sign-in page. Sign in once in Chrome yourself, then check again.' },
+    { id: 'read', label: 'PMOS can read the numbers', state: pass ? 'works' : 'waiting', reason: pass ? 'Read the table "Spend by campaign".' : 'Waits for the step above.' }] });
+  const fixedPlan = (n) => JSON.parse(JSON.stringify(S.plans[n]));
+  const route = async (route) => {
+    const req = route.request(); const u = new URL(req.url()); const p = u.pathname; const m = req.method();
+    const json = (b, status) => route.fulfill({ status: status || 200, contentType: 'application/json', body: JSON.stringify(b) });
+    const body = m === 'POST' ? JSON.parse(req.postData() || '{}') : null;
+    if (m === 'POST') S.posts.push({ path: p, body });
+    if (m === 'GET' && p === '/api/report-structure') { S.polls++; return json(view()); }
+    if (m === 'GET' && p === '/api/report-structure/version') return json({ ok: true, plan: S.plans[Number(u.searchParams.get('n'))] });
+    if (m === 'GET' && p === '/api/report-structure/dry') return json({ ok: true, dry: S.dryResult });
+    if (m === 'GET' && p === '/api/charts') { S.chartsRead++; return json({ ok: true, charts: [{ id: 'new-users', name: 'New users', question: 'Are we still bringing people in?', source: { kind: 'connector', name: 'Google Analytics 4', via: 'Supermetrics' }, from: 'GA4 newUsers', how: 'Month total', compare: 'Previous month', flag: 'Down 10% or more', query: 'GA4 Data API: metric newUsers', why: 'The top of the funnel.', users: [{ kind: 'dashboard', id: 'health', name: 'MySPH health' }, { kind: 'report', id: SETUP.id, name: SETUP.name }] }] }); }
+    if (m === 'POST' && p === '/api/report-structure/turn') {
+      if (S.running) return json({ ok: false, error: 'a report-structure job is already running' }, 409);
+      S.ticks = 0; S.log.push({ who: 'pm', text: body.text, at: now() });
+      let done;
+      if (!S.versions.length && !S.asked) done = () => { S.asked = true; S.log.push({ who: 'pmos', text: 'Before I propose a structure, two questions.', at: now(), questions: Q1, options: [] }); };
+      else if (!S.versions.length) done = () => land('From your answers', plan1(), 'Three ways to shape it. I recommend Funnel first. I drafted it as S1.', { options: OPTIONS });
+      else if (/^Test pull/.test(body.text)) done = () => { S.log.push({ who: 'pmos', text: 'Read it: both charts returned a number.', at: now(), questions: [], options: [] }); };
+      else done = () => { const pl = fixedPlan(S.current); pl.charts.push({ ...CH_RET }); pl.outline.splice(2, 0, SEC('ret', 'Retention by cohort', { charts: ['ret'], notes: 'Do the people we bring in stay?', show: 'Cohort table' })); land('Retention added', pl, 'S2: D30 retention added.'); };
+      S.running = { kind: 'report-structure', done };
+      return json({ ok: true, running: true });
+    }
+    if (m === 'POST' && p === '/api/report-structure/revert') { S.current = body.n; return json({ ok: true, structure: view().structure }); }
+    if (m === 'POST' && p === '/api/report-structure/remove') { const pl = fixedPlan(S.current); if (body.kind === 'chart') { pl.charts = pl.charts.filter((c) => c.id !== body.ref); pl.outline.forEach((o) => { o.charts = o.charts.filter((c) => c !== body.ref); }); } else pl.sources = pl.sources.filter((s) => s.id !== body.ref); land('Remove ' + body.ref, pl, 'Removed ' + body.ref + '.'); return json({ ok: true, structure: view().structure }); }
+    if (m === 'POST' && p === '/api/report-structure/source') {
+      const pl = fixedPlan(S.current); const s = body.source; const grp = ['connector', 'link', 'upload', 'person', 'chrome', 'computer'].includes(s.kind) ? 'outside' : 'pmos';
+      pl.sources.push({ via: '', ref: '', ...s, group: grp, state: s.kind === 'chrome' ? 'needs-you' : 'reached' });
+      land('Add ' + s.name, pl, s.name + ' added.');
+      if (s.kind === 'chrome') S.checks[s.id] = { ...chromeChecks(false), source: s.id };
+      return json({ ok: true, structure: view().structure });
+    }
+    if (m === 'POST' && p === '/api/report-structure/check') { S.checks[body.source] = { ...chromeChecks(true), source: body.source }; const pl = S.plans[S.current]; const s = pl.sources.find((x) => x.id === body.source); if (s) s.state = 'reached'; return json({ ok: true, check: S.checks[body.source] }); }
+    if (m === 'POST' && p === '/api/report-structure/dry') { S.ticks = 0; S.running = { kind: 'report-structure-dry', done: () => { S.dry = { run: 'r1', n: body.n || S.current, at: now(), ok: true };
+      S.dryResult = { n: S.dry.n, period: '2026-09', headline: 'New users fell 8.9% while cost per new user rose 19%.', values: [{ chart: 'new-users', value: '48,210', was: '52,930 in Aug', delta: '-8.9%', flag: true, note: 'down 10% or more is the rule' }, { chart: 'cpa', value: 'IDR 21,900', was: 'IDR 18,400 in Aug', delta: '+19%', flag: false, note: '' }], missing: [{ source: 'bq', reason: 'BigQuery is not connected.' }], options: ['Fix the first 30 days', 'Restart paid acquisition'] }; } }; return json({ ok: true, running: true }); }
+    if (m === 'POST' && p === '/api/report-structure/accept') { S.saved = body.n; return json({ ok: true, structure: view().structure, brief: 'structure/brief.md', charts: ['cpa'] }); }
+    if (m === 'GET' && p === '/api/report-setups') return json({ ok: true, setups: S.setupMade ? [SETUP] : [SETUP], findings: [], asks: S.askShown ? [{ id: 'ask1', text: 'Monthly product performance for leadership, numbers from Google Analytics', state: 'ready', proposal: PROPOSAL }] : [], finder: { cadence: 'off' } });
+    if (m === 'POST' && p === '/api/report-setups/setup') { S.setupMade++; return json({ ok: true, setup: SETUP, drafted: null }); }
+    if (m === 'GET' && p === '/api/report-documents') return json({ ok: true, docs: [] });
+    if (m === 'GET' && p === '/api/report-dashboards') return json({ ok: true, library: [{ id: 'north', title: 'North star', question: 'Are we moving?', source: 'PMOS ledgers' }], layouts: {}, defaults: { board: [], initiative: [] }, boards: [], initiatives: [], schedules: [] });
+    if (m === 'GET' && p === '/api/report-design') return json({ ok: true, setup: { id: SETUP.id, name: SETUP.name }, design: { running: false, current: null, saved: null, versions: [], log: [], samples: [], description: '', format: 'deck' } });
+    return route.continue();
+  };
+  return { S, route };
+}
+
+(async () => {
+  const exe = findBrowser();
+  if (!exe) { console.log('· no Chrome/Chromium on this machine, c3-report-structure suite skipped'); process.exit(0); }
+  let chromium;
+  try { ({ chromium } = require('playwright-core')); } catch { console.log('· playwright-core not installed, c3-report-structure suite skipped'); process.exit(0); }
+  srv = spawn(process.execPath, [path.join(__dirname, 'server.js')], { cwd: __dirname, stdio: 'ignore', env: T.env({ PMOS_WS_PORT: String(T.PORT) }) });
+  await T.waitForServer(BASE);
+  browser = await chromium.launch({ executablePath: exe });
+  require('./lib/c3-full-console').fullConsole(browser);   // the desktop layout at phone width (c3-phone-companion)
+  const shots = process.env.RX_SHOTS || ''; if (shots) fs.mkdirSync(shots, { recursive: true });
+  const shot = async (pg, n) => { if (shots) await pg.screenshot({ path: path.join(shots, n + '.png') }); };
+
+  const errors = [];
+  const stub = makeStub(); const S = stub.S;
+  const ctx = await browser.newContext({ viewport: { width: 1440, height: 1000 } });
+  await ctx.route(/\/api\/(report-structure|charts|report-setups|report-documents|report-dashboards|report-design)/, stub.route);
+  const page = await ctx.newPage();
+  page.on('pageerror', (e) => errors.push('pageerror: ' + String((e && e.message) || e)));
+  page.on('console', (m) => { if (m.type() === 'error' && !/favicon|Failed to load resource/.test(m.text())) errors.push('console: ' + m.text()); });
+  page.on('response', (r) => { if (r.status() >= 400 && !/\/api\/(scan\/(?:today|portfolio)|settings|report-structure)\b/.test(r.url()) && !(r.status() === 409)) errors.push('http ' + r.status() + ' ' + r.url()); });
+  page.on('dialog', (d) => d.dismiss().catch(() => {}));
+  const text = (sel) => page.textContent(sel).catch(() => '');
+  const sent = (p) => S.posts.filter((x) => x.path === p);
+  const closeAll = async () => { for (let i = 0; i < 3 && await page.$('.sheet'); i++) { await page.keyboard.press('Escape'); await sleep(250); } };
+  const goReports = async () => { await page.goto(BASE + '/c3.html?tab=rep'); await page.waitForSelector('[data-rp3]'); await page.click('[data-rp3-tab="reports"]'); await page.waitForSelector('[data-rs-reg="' + SETUP.id + '"]', { timeout: 15000 }); };
+  const idle = () => page.waitForFunction(() => { const b = document.querySelector('[data-st-act="send"]'); return b && !b.disabled && !document.querySelector('[data-st-running]'); }, null, { timeout: 15000 });
+  const noOverflow = () => page.evaluate(() => document.documentElement.scrollWidth <= document.documentElement.clientWidth + 1);
+
+  /* ── entry points ── */
+  S.askShown = true;
+  await goReports();
+  ok('the set-up row has Shape the report before Design how it looks', await page.$$eval('[data-rs-reg="' + SETUP.id + '"] .acts button', (a) => { const t = a.map((b) => b.textContent.trim()); return t.indexOf('Shape the report') > -1 && t.indexOf('Shape the report') < t.indexOf('Design how it looks'); }));
+  await page.waitForSelector('[data-rs-card="ask1"]');
+  ok('an Ask PMOS answer has Shape it with PMOS', !!(await page.$('[data-rs-card="ask1"] [data-rs-act="shape"]')));
+  await page.click('[data-rs-card="ask1"] [data-rs-act="shape"]');
+  await page.waitForSelector('[data-st-studio]');
+  ok('Shape it with PMOS sets the report up, then opens the Structure step', sent('/api/report-setups/setup').length === 1 && sent('/api/report-setups/setup')[0].body.ask === 'ask1' && /Not saved yet/.test(await text('[data-st-studio]')));
+  ok('the step bar says 1 Structure, 2 Design with Structure pressed', await page.getAttribute('[data-st-step-btn="structure"]', 'aria-pressed') === 'true' && /2 Design/.test(await text('[data-st-steps]')));
+  ok('with no version yet the studio asks what the report is for and the Use button waits', !!(await page.$('[data-st-studio] .fold')) && await page.$eval('[data-st-act="save"]', (b) => b.disabled));
+  await closeAll();
+  S.askShown = false;
+  await goReports();
+  await page.click('[data-rs-reg="' + SETUP.id + '"] [data-rs-act="shape"]');
+  await page.waitForSelector('[data-st-studio]');
+  ok('Shape the report on the row opens the same studio', /Not saved yet/.test(await text('[data-st-studio]')));
+  await closeAll();
+  await page.click('[data-rs-reg="' + SETUP.id + '"] [data-rs-act="design"]');
+  await page.waitForSelector('[data-rd-studio]');
+  ok('the Design studio shows the step bar with 2 Design pressed', await page.getAttribute('[data-rd-step="design"]', 'aria-pressed') === 'true' && await page.getAttribute('[data-rd-step="structure"]', 'aria-pressed') === 'false');
+  await page.click('[data-rd-step="structure"]');
+  await page.waitForSelector('[data-st-studio]');
+  ok('1 Structure in the Design studio opens the Structure step', !!(await page.$('[data-st-steps]')));
+  await page.click('[data-st-step-btn="design"]');
+  await page.waitForSelector('[data-rd-studio]');
+  ok('2 Design in the Structure step opens the Design studio', true);
+  await page.click('[data-rd-step="structure"]');
+  await page.waitForSelector('[data-st-studio]');
+
+  /* ── a first turn: PMOS asks, answer chips ── */
+  await page.fill('[data-st-in]', 'I need a monthly product performance report for leadership. Get the numbers from Google Analytics.');
+  await page.click('[data-st-act="send"]');
+  ok('a turn posts the words as ONE turn', !!(await until(() => sent('/api/report-structure/turn').length === 1)) && /monthly product performance/.test(sent('/api/report-structure/turn')[0].body.text));
+  ok('while the job runs the conversation says PMOS is working and Make the next version waits', !!(await until(() => page.$('[data-st-running]'))));
+  await page.waitForSelector('[data-st-question]', { timeout: 15000 });
+  ok('PMOS asks its questions with answer chips', (await page.$$('[data-st-question]')).length === 2 && (await page.$$('[data-st-question] [data-st-act="chip"]')).length === 6);
+  await page.click('[data-st-act="chip"][data-v="Leadership: where to invest next quarter"]');
+  ok('a chip puts its answer in the box', (await page.inputValue('[data-st-in]')) === 'Leadership: where to invest next quarter.');
+  await page.click('[data-st-act="chip"][data-v="Revenue"]');
+  ok('a second chip adds to the box', /next quarter\. Revenue\.$/.test(await page.inputValue('[data-st-in]')));
+  await page.click('[data-st-act="send"]');
+  await page.waitForSelector('[data-st-v="1"]', { timeout: 15000 });
+  ok('the second turn lands S1', (await page.$$('[data-st-v]')).length === 1 && await page.getAttribute('[data-st-v="1"]', 'aria-pressed') === 'true');
+  await page.waitForSelector('[data-st-purpose]');
+  ok('the plan shows What it answers with readers, decision, scope and the questions', /Leadership: Gita Rahma/.test(await text('[data-st-purpose]')) && /Where to invest next quarter/.test(await text('[data-st-purpose]')) && /Where do users drop/.test(await text('[data-st-purpose]')));
+
+  /* ── sources ── */
+  const grp = (g) => page.$$eval('[data-st-group="' + g + '"] + ul > li', (a) => a.map((li) => li.getAttribute('data-st-src')));
+  ok('Sources are grouped: From PMOS and Outside PMOS', JSON.stringify(await grp('pmos')) === '["board","dash","past"]' && JSON.stringify(await grp('outside')) === '["ga","bq"]', JSON.stringify([await grp('pmos'), await grp('outside')]));
+  ok('each source shows its state', await page.getAttribute('[data-st-src="ga"] [data-st-state]', 'data-st-state') === 'reached' && /Not connected/.test(await text('[data-st-src="bq"] [data-st-state]')) && /First cycle: nothing to read/.test(await text('[data-st-src="past"] [data-st-state]')));
+  ok('the actions fit the source: Open, Test pull, How to connect', /Open/.test(await text('[data-st-src="board"] .acts')) && /Test pull/.test(await text('[data-st-src="ga"] .acts')) && /How to connect/.test(await text('[data-st-src="bq"] .acts')));
+  ok('a source says how many charts use it', /2 charts/.test(await text('[data-st-src="ga"]')) && !/ chart/.test(await text('[data-st-src="board"] .chips')));
+  await page.click('[data-st-src="ga"] [data-st-act="test"]');
+  ok('Test pull asks PMOS to read that source (one turn)', !!(await until(() => sent('/api/report-structure/turn').length === 3)) && /Test pull from Google Analytics 4/.test(sent('/api/report-structure/turn')[2].body.text));
+  await idle();
+  await page.click('[data-st-src="bq"] [data-st-act="connect"]');
+  ok('How to connect says where to connect it', /Settings, Connectors/.test(await text('[data-c3-toast]')));
+
+  /* ── charts ── */
+  ok('Charts are tagged New chart and From Charts', await text('[data-st-chart="cpa"] [data-st-tag]') === 'New chart' && await text('[data-st-chart="new-users"] [data-st-tag]') === 'From Charts' && /1 new, 1 from Charts/.test(await text('[data-st-metrics]')));
+  await page.click('[data-st-chart="new-users"] [data-st-act="chart"]');
+  await page.waitForSelector('[data-st-detail="new-users"]');
+  ok('a chart row opens to question, used in, what PMOS reads and why', /Are we still bringing people in/.test(await text('[data-st-q]')) && /GA4 Data API: metric newUsers/.test(await text('[data-st-query]')) && /top of the funnel/.test(await text('[data-st-why]')));
+  ok('Used in names the dashboard and report that use a chart from Charts', !!(await until(async () => /dashboard MySPH health/.test(await text('[data-st-used]')) && /this report/.test(await text('[data-st-used]')))), await text('[data-st-used]'));
+  ok('a chart from Charts has Open in Charts, a new chart does not', !!(await page.$('[data-st-detail="new-users"] [data-st-act="opencharts"]')));
+  await page.click('[data-st-chart="cpa"] [data-st-act="chart"]');
+  ok('only one row is open and a new chart says it is saved in Charts when you use the structure', !!(await page.$('[data-st-detail="cpa"]')) && !(await page.$('[data-st-detail="new-users"]')) && /Saved in Charts when you use this structure/.test(await text('[data-st-used]')) && !(await page.$('[data-st-detail="cpa"] [data-st-act="opencharts"]')));
+  ok('the test pull says it is not tried yet', /Not tried on this version/.test(await text('[data-st-testpull]')));
+  await shot(page, 'structure-logic-1440');
+  await page.click('[data-st-detail="cpa"] [data-st-act="discuss"]');
+  ok('Discuss this chart fills the box with the chart name and focuses it', (await page.inputValue('[data-st-in]')) === 'About Cost per new user: ' && await page.evaluate(() => document.activeElement && document.activeElement.hasAttribute('data-st-in')));
+
+  /* ── the outline ── */
+  ok('the Outline lists the sections in order with chart chips and PMOS notes', JSON.stringify(await page.$$eval('[data-st-section]', (a) => a.map((x) => x.getAttribute('data-st-section')))) === '["headline","funnel","needs","sources"]'
+    && /New users/.test(await text('[data-st-section="funnel"]')) && /PMOS notes/.test(await text('[data-st-section="funnel"]')) && !/PMOS notes/.test(await text('[data-st-section="headline"]')) && /In every report/.test(await text('[data-st-section="headline"]')));
+
+  /* ── a refine turn: S2 ── */
+  await idle();
+  await page.fill('[data-st-in]', 'Add retention by cohort.');
+  await page.click('[data-st-act="send"]');
+  await page.waitForSelector('[data-st-v="2"]', { timeout: 15000 });
+  ok('a refine turn lands S2 and the strip lists S1 and S2', (await page.$$('[data-st-v]')).length === 2 && await page.getAttribute('[data-st-v="2"]', 'aria-pressed') === 'true');
+  await page.waitForSelector('[data-st-chart="ret"]');
+  ok('S2 has the retention chart and a section that says New in S2', !!(await page.$('[data-st-chart="ret"]')) && /New in S2/.test(await text('[data-st-section="ret"]')) && !/New in S2/.test(await text('[data-st-section="funnel"]')));
+  await shot(page, 'structure-1440');
+  await page.$eval('[data-st-sources]', (n) => n.scrollIntoView({ block: 'start' })); await sleep(200); await shot(page, 'structure-sources-1440');
+  ok('the conversation names each version with a link', (await page.$$('[data-st-log] [data-st-act="ver"]')).length === 2);
+  await page.click('[data-st-v="1"]');
+  await until(async () => await page.getAttribute('[data-st-v="1"]', 'aria-pressed') === 'true' && !(await page.$('[data-st-chart="ret"]')));
+  ok('S1 shows again without the retention chart and says it is an older version', !(await page.$('[data-st-chart="ret"]')) && /older version/.test(await text('[data-st-vcap]')));
+  await page.click('[data-st-act="revert"]');
+  ok('Go back to S1 posts a revert for n 1', !!(await until(() => sent('/api/report-structure/revert').length === 1)) && sent('/api/report-structure/revert')[0].body.n === 1);
+  await until(async () => !(await page.$('[data-st-act="revert"]')));
+  await page.click('[data-st-v="2"]');
+  await page.waitForSelector('[data-st-chart="ret"]');
+  await page.click('[data-st-act="revert"]');
+  ok('going back to S2 the same way makes it current again', !!(await until(() => sent('/api/report-structure/revert').length === 2)) && sent('/api/report-structure/revert')[1].body.n === 2);
+  await until(async () => !(await page.$('[data-st-act="revert"]')));
+
+  /* ── Remove it ── */
+  await page.click('[data-st-chart="ret"] [data-st-act="chart"]');
+  await page.click('[data-st-detail="ret"] [data-st-act="drop"]');
+  ok('Remove it posts a remove of that chart', !!(await until(() => sent('/api/report-structure/remove').length === 1)) && sent('/api/report-structure/remove')[0].body.kind === 'chart' && sent('/api/report-structure/remove')[0].body.ref === 'ret');
+  await page.waitForSelector('[data-st-v="3"]', { timeout: 10000 });
+  ok('removing makes the next version, S3, without the chart', !(await page.$('[data-st-chart="ret"]')) && (await page.$$('[data-st-v]')).length === 3);
+
+  /* ── Add a source ── */
+  await page.click('[data-st-act="panel"][aria-expanded]');
+  await page.waitForSelector('[data-st-panel]');
+  const optKinds = await page.$$eval('[data-st-panel] [data-st-act="opt"]', (a) => a.map((b) => b.getAttribute('data-v')));
+  ok('Add a source offers every From PMOS and Outside PMOS kind', JSON.stringify(optKinds) === JSON.stringify(['pmos-level', 'dashboard', 'chart', 'document', 'past-report', 'connector', 'link', 'upload', 'person', 'chrome', 'computer']), optKinds.join(','));
+  ok('the panel has the two groups and says PMOS only reads', /From PMOS/.test(await text('[data-st-panel]')) && /Outside PMOS/.test(await text('[data-st-panel]')) && /PMOS only reads/.test(await text('[data-st-panel]')));
+  await shot(page, 'structure-pmos-1440');
+  await page.click('[data-st-panel] [data-st-act="opt"][data-v="document"]');
+  await page.waitForSelector('[data-st-form="document"]');
+  await page.click('[data-st-form="document"] [data-st-act="add"]');
+  ok('a form needs its name before it adds', sent('/api/report-structure/source').length === 0);
+  await page.fill('[data-st-form="document"] [data-st-field="name"]', 'MySPH strategy 2026');
+  await page.click('[data-st-form="document"] [data-st-act="add"]');
+  ok('a From PMOS source (a document) posts a source of that kind', !!(await until(() => sent('/api/report-structure/source').length === 1)) && sent('/api/report-structure/source')[0].body.source.kind === 'document' && sent('/api/report-structure/source')[0].body.source.name === 'MySPH strategy 2026' && !('state' in sent('/api/report-structure/source')[0].body.source));
+  await page.waitForSelector('[data-st-v="4"]', { timeout: 10000 });
+  ok('it joins the From PMOS group in S4', JSON.stringify(await grp('pmos')) === '["board","dash","past","mysph-strategy-2026"]', JSON.stringify(await grp('pmos')));
+  await page.click('[data-st-act="panel"][aria-expanded]');
+  await page.click('[data-st-panel] [data-st-act="opt"][data-v="chrome"]');
+  await page.waitForSelector('[data-st-form="chrome"]');
+  await page.fill('[data-st-form="chrome"] [data-st-field="name"]', 'Looker Studio: Paid acquisition');
+  await page.fill('[data-st-form="chrome"] [data-st-field="ref"]', 'not a link');
+  await page.click('[data-st-form="chrome"] [data-st-act="add"]');
+  ok('a Chrome page needs a link that starts with https://', /starts with https/.test(await text('[data-c3-toast]')) && !S.posts.some((x) => x.body && x.body.source && x.body.source.kind === 'chrome'));
+  await page.fill('[data-st-form="chrome"] [data-st-field="ref"]', 'https://lookerstudio.google.com/reporting/abc');
+  await page.click('[data-st-form="chrome"] [data-st-act="add"]');
+  await page.waitForSelector('[data-st-check]', { timeout: 10000 });
+  const lid = sent('/api/report-structure/source').pop().body.source.id;
+  ok('a Chrome source shows its check step by step', (await page.$$('[data-st-check] [data-st-step]')).length === 5 && await page.getAttribute('[data-st-check] [data-st-step="signed-in"]', 'data-st-step-state') === 'needs-you');
+  ok('a failing step says Needs you with its reason; the steps after it Wait', /Needs you/.test(await text('[data-st-step="signed-in"]')) && /Sign in once in Chrome/.test(await text('[data-st-step="signed-in"]')) && /Waiting/.test(await text('[data-st-step="read"]')) && /Works/.test(await text('[data-st-step="mac"]')));
+  ok('the check says one step needs you, what the session may do, and the 4 hour wait', /1 step needs you/.test(await text('[data-st-check-state]')) && /Only the browser tools/.test(await text('[data-st-check]')) && /up to 4 hours/.test(await text('[data-st-check]')));
+  ok('the source row is in Outside PMOS with Needs you and Check it works', /Needs you/.test(await text('[data-st-src="' + lid + '"] [data-st-state]')) && /Check it works/.test(await text('[data-st-src="' + lid + '"] .acts')) && /Re-checked 1 hour before each draft/.test(await text('[data-st-src="' + lid + '"]')));
+  await shot(page, 'structure-browser-1440');
+  ok('Check again is offered', /Check again/.test(await text('[data-st-check] [data-st-act="chkagain"]')));
+  await page.click('[data-st-check] [data-st-act="chkagain"]');
+  ok('Check again posts a check for that source', !!(await until(() => sent('/api/report-structure/check').length === 1)) && sent('/api/report-structure/check')[0].body.source === lid);
+  await until(async () => /All steps work/.test(await text('[data-st-check-state]')));
+  ok('the second check passes: every step Works and the source is Reached', /All steps work/.test(await text('[data-st-check-state]')) && (await page.$$eval('[data-st-check] [data-st-step-state="works"]', (a) => a.length)) === 5 && /Reached/.test(await text('[data-st-src="' + lid + '"] [data-st-state]')));
+  await shot(page, 'structure-browser-ok-1440');
+  await page.click('[data-st-src="' + lid + '"] [data-st-act="chkopen"]');
+  ok('Check it works on the row posts a check', !!(await until(() => sent('/api/report-structure/check').length === 2)));
+
+  /* ── Other structures ── */
+  await page.click('[data-st-view="options"]');
+  await page.waitForSelector('[data-st-options]');
+  ok('Other structures shows three side by side with the recommended first', JSON.stringify(await page.$$eval('[data-st-option]', (a) => a.map((x) => x.getAttribute('data-st-option')))) === '["Funnel first","Goals first","Features first"]' && /Recommended/.test(await text('[data-st-option="Funnel first"]')));
+  ok('each option has its sections, good for and misses', /GOOD FOR/.test(await text('[data-st-option="Goals first"]')) && /MISSES/.test(await text('[data-st-option="Goals first"]')) && (await page.$$('[data-st-option="Goals first"] li')).length === 3);
+  const cols = await page.$$eval('[data-st-option]', (a) => a.map((x) => Math.round(x.getBoundingClientRect().top)));
+  ok('the three options sit in one row at 1440 wide', cols.every((t) => Math.abs(t - cols[0]) < 4), cols.join(','));
+  await shot(page, 'structure-options-1440');
+  await page.click('[data-st-option="Goals first"] [data-st-act="choose"]');
+  ok('Use this instead puts the choice in the box and goes back to the plan', (await page.inputValue('[data-st-in]')) === 'Use the "Goals first" structure instead.' && await page.getAttribute('[data-st-view="plan"]', 'aria-pressed') === 'true');
+  await page.fill('[data-st-in]', '');
+
+  /* ── Try it with real data ── */
+  await page.click('[data-st-view="dry"]');
+  await page.waitForSelector('[data-st-nodry]');
+  ok('Try it with real data explains that it reads only and saves nothing', /saves nothing/.test(await text('[data-st-nodry]')));
+  await page.click('[data-st-act="dryrun"]');
+  ok('the run posts ONE dry job for the version on screen', !!(await until(() => sent('/api/report-structure/dry').length === 1)) && sent('/api/report-structure/dry')[0].body.n === 5);
+  ok('while it runs the view says so and nothing is saved', !!(await until(() => page.$('[data-st-dryrunning]'))));
+  await page.waitForSelector('[data-st-dry-headline]', { timeout: 15000 });
+  ok('the result shows the headline PMOS would write', /New users fell 8\.9%/.test(await text('[data-st-dry-headline]')));
+  ok('the values show each chart with its comparison', /New users/.test(await text('[data-st-dry-values]')) && /48,210/.test(await text('[data-st-dry-values]')) && /52,930 in Aug/.test(await text('[data-st-dry-values]')) && /\+19%/.test(await text('[data-st-dry-values]')));
+  ok('a flagged value is flagged and listed under Flags', /Flagged/.test(await text('[data-st-dry-values]')) && /New users/.test(await text('[data-st-dry-flags]')));
+  ok('what it could not get names the source and why', /BigQuery/.test(await text('[data-st-dry-missing]')) && /not connected/.test(await text('[data-st-dry-missing]')));
+  ok('the options PMOS would propose show, with the note that the PM decides', /Fix the first 30 days/.test(await text('[data-st-dry-options]')) && /PMOS never decides them/.test(await text('[data-st-dry-options]')));
+  await shot(page, 'structure-dry-1440');
+  await page.click('[data-st-view="plan"]');
+  await page.click('[data-st-chart="cpa"] [data-st-act="chart"]');
+  ok('a chart row now shows its test pull value', /IDR 21,900/.test(await text('[data-st-testpull]')) && /\+19%/.test(await text('[data-st-testpull]')));
+
+  /* ── Use this structure ── */
+  await page.click('[data-st-act="save"]');
+  ok('Use this structure posts the version on screen', !!(await until(() => sent('/api/report-structure/accept').length === 1)) && sent('/api/report-structure/accept')[0].body.n === 5);
+  await page.waitForSelector('[data-rd-brief]', { timeout: 10000 });
+  await page.waitForSelector('[data-st-saved-wrap]');
+  ok('the report setup sheet shows the saved structure beside the Design', /Structure S5/.test(await text('[data-st-saved-tag]')) && !!(await page.$('[data-rd-design]')));
+  ok('the saved structure lists what it answers, the sources, the charts and the outline', /Where to invest next quarter/.test(await text('[data-st-answers]')) && /MySPH strategy 2026/.test(await text('[data-st-brief]')) && /Cost per new user/.test(await text('[data-st-brief]')) && /Needs your call/.test(await text('[data-st-brief]')));
+  ok('it offers Refine the structure and Try it with real data', /Refine the structure/.test(await text('[data-st-brief]')) && /Try it with real data/.test(await text('[data-st-brief]')));
+  ok('it says a change applies from the next cycle and the Chrome source is re-checked', /applies from the next cycle/.test(await text('[data-st-saved-wrap]')) && /Looker Studio: Paid acquisition/.test(await text('[data-st-saved-wrap]')) && /waits up to 4 hours/.test(await text('[data-st-saved-wrap]')));
+  await shot(page, 'structure-saved-1440');
+  await page.click('[data-st-brief] [data-st-act="opendry"]');
+  await page.waitForSelector('[data-st-studio]');
+  ok('Try it with real data in the setup sheet opens the studio on that view', await page.getAttribute('[data-st-view="dry"]', 'aria-pressed') === 'true' && /Saved structure: S5/.test(await text('[data-st-studio]')));
+  await closeAll();
+
+  /* ── the Charts tab ── */
+  await goReports();
+  await page.click('[data-rp3-tab="charts"]');
+  await page.waitForSelector('[data-rp3-data-chart="new-users"]');
+  ok('the Charts tab lists a data chart beside the built-in ones', !!(await page.$('[data-rp3-lib] [data-home="north"]')) && !!(await page.$('[data-rp3-lib] [data-rp3-data-chart="new-users"]')) && /Data chart/.test(await text('[data-rp3-data-chart="new-users"]')));
+  ok('the data chart shows its source and Used in', /Google Analytics 4 through Supermetrics/.test(await text('[data-rp3-source="new-users"]')) && /Used in: .*MySPH health.*MySPH app performance, monthly/.test(await text('[data-rp3-data-chart="new-users"] [data-rp3-used]')));
+  ok('the Charts tab counts both kinds', /2/.test(await text('[data-rp3-tab="charts"]')));
+  await page.click('[data-rp3-data-chart="new-users"] .tt').catch(() => {});
+  await shot(page, 'structure-charts-tab-1440');
+
+  /* ── the saved structure and the studio at 400 wide ── */
+  await page.setViewportSize({ width: 400, height: 900 });
+  await goReports();
+  ok('at 400 wide the Reports tab does not scroll sideways', await noOverflow());
+  await page.click('[data-rs-reg="' + SETUP.id + '"] [data-rs-act="shape"]');
+  await page.waitForSelector('[data-st-chart]');
+  ok('at 400 wide the Structure step does not scroll sideways', await noOverflow());
+  await shot(page, 'structure-400');
+  await page.click('[data-st-chart="cpa"] [data-st-act="chart"]');
+  await page.click('[data-st-act="panel"][aria-expanded]');
+  await page.waitForSelector('[data-st-panel]');
+  ok('at 400 wide the open chart and the Add a source panel do not scroll the page sideways', await noOverflow());
+  await shot(page, 'structure-pmos-400');
+  await page.click('[data-st-view="options"]');
+  ok('at 400 wide Other structures stack and do not scroll sideways', await noOverflow());
+  await shot(page, 'structure-options-400');
+  await page.click('[data-st-view="dry"]');
+  ok('at 400 wide the dry run does not scroll sideways', await noOverflow());
+  await shot(page, 'structure-dry-400');
+  await page.setViewportSize({ width: 1440, height: 1000 });
+
+  ok('no script error and no failed request', errors.length === 0, errors.join(' | '));
+  await finish();
+})().catch((e) => { console.error(e); finish(1); });

package/workspace/guide/briefing.md

@@ -1,13 +1,13 @@
 ---
 type: Guide
 title: "The Briefing: today's brief"
-description: "The Briefing page of the console (/): the headline cards, Today, Needs you, Portfolio pulse, and what Done, Not yet and Drop do to an item."
+description: "The Briefing page of the console (/): The brief, the headline cards, Today, Needs you, Mentions, Portfolio pulse, and what Done, Not yet and Drop do to an item."
 timestamp: 2026-10-14
 ---
 
 # The Briefing: today's brief
 
-The Briefing is the first page of the console at `/`. It has two columns. The left column holds the greeting, the headline cards and Needs you. The right column holds Today and Portfolio pulse. It holds no calendar. The full calendar is the Calendar tab.
+The Briefing is the first page of the console at `/`. It has two columns. The left column holds the greeting, The brief, the headline cards, Needs you and Mentions. The right column holds Today and Portfolio pulse. It holds no calendar. The full calendar is the Calendar tab.
 
 Review is in the Work page, in its Review lens. Handled, What I could stop and Data you can lean on are in Reports, under Drafts.
 
@@ -35,6 +35,20 @@ Overdue cards come first, the most late first. The signal engine's cards come ne
 
 Above the cards, the greeting names the part of the day, for example "Good morning, Wawan". The name is the first word of the git user name on the computer where PMOS runs. When git holds no name, the greeting has none. The part of the day follows the clock. There is no button to change it. When the clock moves to a new part, the line under the greeting and the order of the cards change after you stop using the page for a minute.
 
+## The brief
+
+The brief is one paragraph under the greeting, above the headline cards. Read it to know the day in a few seconds. It says, in this order:
+
+1. The one decision that the day turns on. When no row is a decision that only you can make, it names the first row of Needs you.
+2. How many things need you, how many are overdue, and the oldest overdue item.
+3. Who waits for your reply to a mention.
+4. How many meetings are left today, and the next meeting that still has a to-do before it.
+5. Which initiatives are off track or at risk, and how many are on track.
+
+Each number and each title comes from a row on the page. The count of things that need you is the same as the count of Needs you. Press a title to go to its row. The line at the right of the title says when PMOS wrote the paragraph and which sections it read. When a section changes, for example when you mark an item done, the paragraph changes too. In the evening the paragraph says what is still open and how many meetings you held.
+
+PMOS writes the paragraph from the rows on the page. It does not call a model and it does not write a record.
+
 ## Today
 
 Today starts with one line: the meeting that is on now or next, how many meetings are left, and how many of them are prepped, with a small ring. **Open calendar** opens the calendar. Under it, Today lists the meetings of the day, in time order. Each row shows:
@@ -73,6 +87,20 @@ Press a row to open it in place. A row of your own item has three actions. Each
 
 PMOS can see evidence that an outside item is done. For example, a meeting with the person is on the calendar. Then the row says "Looks done: a meeting with Ana is booked Tue 10:00. Confirm?" PMOS never marks the item done itself. The item changes only when you press **Done** or **Yes, it is done**.
 
+## Mentions
+
+Mentions lists the places where someone mentioned you today: Slack, Jira, Confluence and mail. The list comes from today's morning brief. When there is no morning brief for today, Mentions says so.
+
+The section is quiet. It shows one line that names who waits for your reply, for example "Priya in Slack and Dara in Jira are waiting on your reply." The header says how many need a reply. Press **Show all** to open the list. A tab for each source filters the list. Each row shows the person, the text they wrote, the source and the place, the time, and **needs your reply** or **for your information**. Each row has these actions:
+
+- **Open in Slack** (or Jira, Confluence, Mail) opens the mention in a new tab. A mention with no link has no such button.
+- **Add to Work** adds an item to your Work list, for example "Reply to Dara (Jira) by today".
+- **Mark read** removes the row from the list. Press **Undo** in the notice to bring it back.
+
+A mention that is already a row of Needs you does not show again in Mentions. That row in Needs you has a **mentioned you** tag.
+
+PMOS does not reply, react or post in Slack, Jira, Confluence or mail.
+
 ## Portfolio pulse
 
 Portfolio pulse says how many initiatives need attention, then shows one bar for the status of the initiatives and one row for each initiative. An initiative shows when it has a promised date, or when PMOS holds a read of its Jira epic. A row from a Jira epic shows "3 of 8 done" and a bar. "Done" counts the tickets under the epic that are done in Jira. A row with blocked tickets says **Blocked**. The Jira read is the last Jira status check; the opened row says its date. When no initiative has a promised date or a Jira read, the pulse says so. **All initiatives** at the bottom opens the Initiatives page. Press a row to open it in place. It shows why the initiative has that status, the promised date against the forecast, and the Jira progress when PMOS holds it. The page does not change.
@@ -85,6 +113,6 @@ An item has its actions in one place only. On the Briefing, Today and Portfolio
 
 ## On a phone
 
-At 400 pixels wide the Briefing is one column (greeting, cards, Needs you, Today, Portfolio pulse) with no sideways scroll. Each button in an opened row is 44 pixels high.
+At 400 pixels wide the Briefing is one column (greeting, The brief, cards, Needs you, Mentions, Today, Portfolio pulse) with no sideways scroll. Each button in an opened row is 44 pixels high.
 
 On a phone, every console page has the same top. The page title has Record at its right. The sunrise line is under it, then the tool buttons in one row. The five tabs share the width, and each tab shows an icon over its name, so Initiatives and Reports are always on screen. A count shows at the top right of its tab's icon. A person in a row shows as a small round letter, and you can tap anywhere in the 44-pixel square around it. A line that has a sentence and a due date wraps like normal text.

package/workspace/guide/index.md

@@ -74,6 +74,8 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Report slides](report-slides.md): how the Reports page shows a report as the PM-OS biweekly slides, Present and Print / PDF, and how your notes become the words on the slides.
 - [Reports: dashboards of reports](reports-dashboards.md): the console Reports page, its dashboards at portfolio, board and initiative scope, how to edit one, how to send one as a report, and the Charts tab.
 - [Set up a report by asking, and the report finder](reports-set-up.md): how to ask PMOS to draft a report you send, how the finder finds reports you already send, and how a cycle becomes a document.
+- [Shape what a report says: the Structure step](report-structure.md): how to decide with PMOS what a report answers, where each number comes from and how it is worked out, add a page in Chrome or an app as a source, and try the plan on real data.
+- [Shape what a report says: the Structure step](report-structure.md): how to decide with PMOS what a report answers, where each number comes from and how it is worked out, add a page in Chrome or an app as a source, and try the plan on real data.
 - [Design how a report looks, and read it as a deck](report-design.md): how to design a report in the design studio, read each cycle as a deck or an interactive document, present it, and use speaker notes and notes on the slide.
 - [The document sheet](document-sheet.md): read a document as rich text, edit it, accept the agent's proposals section by section, read the edit log, and clear a stale document.
 - [Ask the agent from the page](ask-the-agent.md): the five presses that start an agent from the console, what the agent may do, and what stays yours.

package/workspace/guide/report-design.md

@@ -13,6 +13,10 @@ There is no template to fill in. You describe the report, add samples, and refin
 
 ## Open the design studio
 
+Design is step 2 of the report studio. Step 1 is Structure, which decides what the report says (see [Shape what a report says](report-structure.md)). Press **1 Structure** at the top of the studio to go to it.
+
+Design is step 2 of the report studio. Step 1 is Structure, which decides what the report says (see [Shape what a report says](report-structure.md)). Press **1 Structure** at the top of the studio to go to it.
+
 Use one of these two buttons:
 
 - In the **Set up** list of the Reports tab, press **Design how it looks** on the row of the report.

package/workspace/guide/report-structure.md

@@ -0,0 +1,91 @@
+---
+type: Guide
+title: "Shape what a report says: the Structure step"
+description: "How to decide with PMOS what a report answers, where each number comes from and how it is worked out, in the Structure step of the report studio, and how to try the plan on real data before you design it."
+timestamp: 2026-10-14
+---
+
+# Shape what a report says
+
+The report studio has two steps: **1 Structure** and **2 Design**. Structure decides what the report says. Design decides how it looks. Do Structure first.
+
+In Structure you talk with PMOS. You say what the report is for. PMOS asks what it needs and writes a report plan. The plan shows what the report answers, where each number comes from, how each number is worked out, and the order of the sections.
+
+## Open the Structure step
+
+Use one of these:
+
+- In **Ask PMOS** on the Reports tab, press **Shape it with PMOS** on the answer. PMOS sets the report up and opens Structure.
+- In the **Set up** list, press **Shape the report** on the row of the report.
+- In the Design studio, press **1 Structure** at the top.
+
+To go to the Design studio from Structure, press **2 Design**.
+
+## Talk it through
+
+1. Write what the report is for, who reads it and what they decide with it. Press **Make the first version**.
+2. PMOS can ask questions first. Each question has answer chips. Press a chip to put the answer in the box. You can press more than one, and edit the words. Press **Make the next version**.
+3. PMOS makes **S1**. It can also propose up to three structures. Press **See the three structures side by side** to read them.
+4. Write what to change and press **Make the next version**. A turn that changes the plan makes a new version: S2, S3 and so on. A turn that only asks a question makes no new version.
+
+A turn takes a minute or two. You can close the studio. The version is ready when you open it again.
+
+## Read the plan
+
+The strip at the top right lists the versions. Press a version to read it. On an older version, press **Go back to** that version to build on it again. The later versions stay in the strip.
+
+The plan has these parts:
+
+- **What it answers.** The readers, the decision, the scope, how often, and the questions the report answers.
+- **Sources.** Where the numbers come from. They are in two groups.
+  - **From PMOS.** A portfolio, board or initiative, a dashboard, a chart, a document, or a past report. A document gives PMOS context for its notes, never numbers. A past report gives last cycle's numbers. In the first cycle there is nothing to read.
+  - **Outside PMOS.** A connector you have (for example Google Analytics through Supermetrics), a link, a file you upload each cycle, a person who gives a number each cycle, a page read in Chrome, or an app on your Mac.
+  - Each source shows its state: **Reached**, **Not connected**, **First cycle: nothing to read** or **Needs you**. It also shows how it is read and how many charts use it. Press **Test pull** to ask PMOS to read it now. Press **Check it works** on a Chrome page or an app on your Mac. Press **How to connect** for a connector that is not connected. Press **Open** for a source in PMOS.
+- **Charts.** Every number is a chart: one question, its source, how it is worked out, what it is compared with, and when it is flagged. A chart that PMOS proposes is tagged **New chart**. A chart that already exists in Reports is tagged **From Charts**. Press a chart to see the question, where it is used, exactly what PMOS reads, why PMOS proposed it and its test value. Press **Discuss this chart** to put its name in the box. Press **Open in Charts** to see a chart from Charts. Press **Remove it** to make the next version without the chart.
+- **Outline.** The sections in order. Each section lists its charts and says if PMOS writes notes on them. **Headline**, **Needs your call** and **Sources** are in every report. You decide everything between them.
+
+Press **Other structures** to read the structures PMOS proposed side by side. The one PMOS recommends is first. Press **Use this instead** to put the choice in the box, then press **Make the next version**.
+
+## Add a source
+
+Press **Add a source** under the conversation. Choose the kind, write its name and press **Add**. A source from outside PMOS that needs a link asks for one. PMOS reads every source and never writes to one. A connector that your Claude settings do not allow stays closed.
+
+## Add a page in Chrome or an app on your Mac
+
+Some numbers are in a page that has no connector, or in an app. PMOS can read a page with Claude in Chrome, or an app with computer use. Both run on your Mac, with your own sign-in.
+
+When you add one, PMOS checks it step by step. Each step says **Works**, **Needs you** or **Waiting**, with a plain reason:
+
+1. PMOS runs on this Mac.
+2. A session can start with Claude in Chrome (or with computer use).
+3. Claude in Chrome answers (or macOS allows the screen and the mouse and keyboard).
+4. You are signed in.
+5. PMOS can read the numbers.
+
+If a step says **Needs you**, do what it says, then press **Check again**. PMOS never types a password. The check session can only open the page, read it and scroll. It cannot submit a form or change a setting, and it closes its tab. Computer use runs only when your own Claude Code settings allow it. If they do not, the check says so.
+
+When a draft is due, PMOS checks that source again. If the check fails, Work shows what to do. The draft waits up to 4 hours. After that it is drafted without that source and says so under Sources. PMOS never guesses a number.
+
+## Try it with real data
+
+Press **Try it with real data** to run the plan on the last complete period, before any design. PMOS shows:
+
+- the headline it would write,
+- the value of each chart, with what it is compared with,
+- the flags,
+- what it could not get, and why,
+- the options it would propose where the outline asks for a choice.
+
+This only reads. It saves nothing in the report and sends nothing.
+
+## Save the structure
+
+Press **Use this structure** to save the version on screen. PMOS saves each new chart in **Reports**, **Charts**. A chart from Charts is not copied: if you change it there, it changes everywhere it is used.
+
+The report setup sheet then shows the saved structure with **Refine the structure** and **Try it with real data**. Each next draft follows it: the sections in order, each number worked out by the saved logic, and the sources it reached and did not reach listed under **Sources**. A change to the structure applies from the next cycle. A cycle that was already issued keeps the structure it was drafted with.
+
+Then press **Design how it looks** to do step 2.
+
+Nothing is sent from Structure.
+
+See also [Design how a report looks](report-design.md), [Set up a report by asking](reports-set-up.md) and [Reports: dashboards of reports](reports-dashboards.md).