@cspeach/cli 1.1.14 → 1.1.16

package/dist/session/user-prompt.js

@@ -0,0 +1,23 @@
+/**
+ * The prompt text of a user message: string content as-is, or the joined
+ * text blocks of array content that carries no tool_result. null for
+ * tool_result rounds, text-less arrays and non-user messages.
+ */
+export function userPromptText(m) {
+    if (m.role !== 'user')
+        return null;
+    if (typeof m.content === 'string')
+        return m.content;
+    if (!Array.isArray(m.content))
+        return null;
+    const blocks = m.content;
+    if (blocks.some((b) => b?.type === 'tool_result'))
+        return null;
+    const texts = blocks
+        .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text);
+    return texts.length > 0 ? texts.join('\n') : null;
+}
+export function isUserPrompt(m) {
+    return userPromptText(m) !== null;
+}

package/dist/skill-catalog.js

@@ -19,36 +19,42 @@ export const SKILL_CATALOG = [
         category: 'Read / Analyze',
         description: 'Impact analysis before changes — traces usage, callers, transports',
         whenToUse: 'pick this for blast radius before a change (not /abap-explain — explain = teach the code)',
+        asks: 'which object? e.g. "ZCL_ORDER_UTILS" or "what breaks if I change ZSD_ORDER_RELEASE"',
     },
     {
         name: 'abap-explain',
         category: 'Read / Analyze',
         description: 'Understand an object — plain-language (default) or `technical` orientation (deps, tables, risks)',
         whenToUse: `plain teaching, or technical=fast orientation (not /abap-impact = blast radius)`,
+        asks: 'which object, plain or technical? e.g. "ZFI_DUNNING_SELECT in plain words"',
     },
     {
         name: 'abap-review',
         category: 'Read / Analyze',
         description: 'Read-only review across lenses: quality (default), performance, cloud-readiness',
         whenToUse: `grade source: quality (default) + performance/cloud lenses`,
+        asks: 'which object, and which lens? e.g. "ZCL_CREDIT_SVC for performance"',
     },
     {
         name: 'abap-clean-core',
         category: 'Read / Analyze',
         description: 'Clean-core decision & defense — recommend the clean-core-correct approach, classify the level (A/B/C/D), produce citable evidence; verifies live when connected. Read-only.',
         whenToUse: `pick this for "is this clean-core-OK?" decisions + defendable evidence (not /abap-review cloud lens — that grades code)`,
+        asks: 'which object or requirement? e.g. "can I add a field to VBAK the clean way"',
     },
     {
         name: 'abap-handover',
         category: 'Read / Analyze',
         description: 'Documentation for one object (`object` scope) or a whole package (`package` scope)',
         whenToUse: `object doc OR full package handover dossier`,
+        asks: 'which object or package? e.g. "package ZTEST_LAS, full handover"',
     },
     {
         name: 'abap-dump',
         category: 'Read / Analyze',
         description: 'Diagnose ABAP short dumps (ST22) and fix them — root cause, call stack, fix with approval; ask for "triage" for ranked read-only hypotheses',
         whenToUse: `pick this for any ST22 dump — diagnose + fix by default, say "triage" for read-only ranking (not /abap-incident — that's the full dump-to-transport pipeline)`,
+        asks: 'which dump? e.g. "the dump in ZFIN_DOC_JOURNAL this morning"',
     },
     // ── Modify / Fix ─────────────────────────────────────────────────────────
     {
@@ -56,48 +62,56 @@ export const SKILL_CATALOG = [
         category: 'Modify / Fix',
         description: 'Run ATC checks against an object and auto-fix findings with safety gates',
         whenToUse: `pick this for ad-hoc ATC fix on one object (not /abap-upgrade-fix — that's worklist-driven)`,
+        asks: 'which object or package? e.g. "ZCL_ORDER_UTILS, fix what is safe"',
     },
     {
         name: 'abap-refactor',
         category: 'Modify / Fix',
         description: 'Refactor a Z object in place — FORM→method, SELECT *→specific fields, guard clauses, inline DATA. Same architecture, cleaner code.',
         whenToUse: `pick this to clean up YOUR Z code, same architecture (not /abap-modernize — that rebuilds as RAP/Fiori)`,
+        asks: 'which object and what change? e.g. "ZLEGACY_FI_REPORT — add a net amount column"',
     },
     {
         name: 'abap-enhance',
         category: 'Modify / Fix',
         description: 'Extend SAP standard via BAdI implementations, enhancement spots, user exits',
         whenToUse: `pick this to hook into SAP-STANDARD code via BAdI/exit (not /abap-refactor — that's for YOUR Z code)`,
+        asks: 'which SAP object and what behaviour? e.g. "block goods issue when the credit check fails"',
     },
     {
         name: 'abap-extend-model',
         category: 'Modify / Fix',
         description: 'Add a field or @UI column to an EXISTING custom CDS view / DDLX metadata extension in place — anchored insertion, snapshot, syntax-check, activate, republish-if-needed. The Fiori Elements column-add.',
         whenToUse: `pick this to add a field/column to an EXISTING custom CDS/DDLX in place (not /abap-rap — that's a new stack; not /abap-refactor — that's ABAP code, not CDS)`,
+        asks: 'which view or BO, and what to add? e.g. "add ShippingPoint to the ZC_Delivery list"',
     },
     {
         name: 'abap-incident',
         category: 'Modify / Fix',
         description: 'End-to-end incident pipeline — dump to fix deployed to transport in one skill',
         whenToUse: `pick this for full ST22-to-transport pipeline with formal report (not /abap-dump — single fix only)`,
+        asks: 'the incident. e.g. "dump in ZOPEN_ORDER_REPORT, users blocked"',
     },
     {
         name: 'abap-test',
         category: 'Modify / Fix',
         description: 'Generate ABAP Unit test classes for existing code with dependency injection',
         whenToUse: `pick this to generate + run ABAP Unit tests (not /abap-eml — EML body only)`,
+        asks: 'which class? e.g. "unit tests for ZCL_CREDIT_SVC"',
     },
     {
         name: 'abap-eml',
         category: 'Modify / Fix',
         description: 'Write and test EML (Entity Manipulation Language) for RAP business objects',
         whenToUse: `pick this for EML inside a RAP context (not /abap-test — that's the test class)`,
+        asks: 'what the EML should do. e.g. "create a draft inspection and activate it"',
     },
     {
         name: 'abap-segw',
         category: 'Modify / Fix',
         description: 'Implement SEGW OData DPC_EXT method bodies — reads generated MPC/DPC base classes. SEGW project itself created in transaction SEGW. For S/4 1909+ RAP services use /abap-rap.',
         whenToUse: `pick this for DPC_EXT method bodies on an EXISTING SEGW project (ECC / older S/4; not /abap-rap — that's S/4 1909+ RAP; SEGW project + MPC/DPC must already exist)`,
+        asks: 'which project and operation? e.g. "GET_ENTITYSET for ZORDER_SRV"',
     },
     // ── Create / Generate ────────────────────────────────────────────────────
     {
@@ -105,30 +119,35 @@ export const SKILL_CATALOG = [
         category: 'Create / Generate',
         description: 'Generate ONE ABAP class / program / include from a clear scope — asks clarifying questions first per Forge Rule 1. For a full RAP stack use /abap-rap; for DDIC only use /abap-data-model.',
         whenToUse: `pick this for ONE class/program/include from clear scope (not /abap-rap — that's a full RAP stack; not /abap-data-model — that's DDIC only)`,
+        asks: 'what to build, or the scope. e.g. "all changes" after a design, or "a report of open orders by plant"',
     },
     {
         name: 'abap-rap',
         category: 'Create / Generate',
         description: 'Scaffold a complete RAP stack on S/4HANA 1909+ — table, CDS interface, projection, BDEF, BP class, SRVD, SRVB, DDLX, DCL. ECC/older S/4 → use /abap-segw.',
         whenToUse: `pick this for a full RAP stack on S/4 1909+ (10 objects, table → SRVB; not /abap-segw — that's ECC/older S/4 OData; not /abap-generate — that's one object)`,
+        asks: 'the business object. e.g. "maintenance requests with draft and an approve action"',
     },
     {
         name: 'abap-fiori-build',
         category: 'Create / Generate',
         description: 'Build a working freestyle SAPUI5 app on the laptop from a published OData service — scaffold, pages, dialogs, chart, value help, local preview. Freestyle only, not Fiori Elements.',
         whenToUse: `pick this for a freestyle UI5 frontend on a published OData service (not /abap-rap — that's the backend; produces local files, not ADT objects)`,
+        asks: 'which service and what UI? e.g. "list + object page on ZUI_LAS_INSPECTIONLOG_O4"',
     },
     {
         name: 'abap-data-model',
         category: 'Create / Generate',
         description: 'Design and create DDIC objects — domains, data elements, tables, structures',
         whenToUse: `pick this for DDIC ONLY — domain/data element/table/structure (step after /abap-design; embedded inside /abap-rap step 1 — call standalone when you don't need the rest of the stack)`,
+        asks: 'the tables and fields. e.g. "inspection results, header and items"',
     },
     {
         name: 'abap-modernize',
         category: 'Create / Generate',
         description: 'Transform classic ABAP to the best modern architecture for the target release (ECC→SEGW, S/4→RAP)',
         whenToUse: `pick this to rebuild a WRITE/dynpro/FM as Fiori/RAP (not /abap-upgrade-fix — that's syntax patches)`,
+        asks: 'which program? e.g. "ZLEGACY_SD_PROCESS onto a modern stack"',
     },
     // ── Upgrade / Migrate ────────────────────────────────────────────────────
     {
@@ -136,42 +155,49 @@ export const SKILL_CATALOG = [
         category: 'Upgrade / Migrate',
         description: 'Custom code analysis pipeline for S/4 upgrade — whole-estate inventory + tier classification + ATC findings + report. Multi-session project with state file.',
         whenToUse: `pick this to discover + classify the whole custom estate (not /abap-migrate — that's per object)`,
+        asks: 'which package or namespace? e.g. "Z*" or "package ZTEST_LAS"',
     },
     {
         name: 'abap-upgrade-scan',
         category: 'Upgrade / Migrate',
         description: 'Scan custom ABAP code for S/4HANA upgrade findings via ATC readiness variant',
         whenToUse: 'pick this to baseline ATC for one package + S/4 release (step 1 of 3 — feeds /abap-upgrade-fix)',
+        asks: 'the scope. e.g. "package ZTEST_LAS" or "Z* with the S/4 readiness variant"',
     },
     {
         name: 'abap-upgrade-fix',
         category: 'Upgrade / Migrate',
         description: 'AI-guided upgrade remediation — fixes ATC findings one object at a time with approval gates',
         whenToUse: 'pick this to fix the upgrade-scan baseline object-by-object (step 2 of 3 — needs /abap-upgrade-scan first)',
+        asks: 'which findings. e.g. "@upgrade-progress" or "the API findings in ZCL_ORDER_UTILS"',
     },
     {
         name: 'abap-upgrade-verify',
         category: 'Upgrade / Migrate',
         description: 'Verify remediation results — re-runs ATC with same variant, compares before/after finding counts',
         whenToUse: 'pick this for the customer sign-off report after fixing (step 3 of 3 — re-runs ATC vs baseline)',
+        asks: 'which scan to verify against. e.g. "@upgrade-progress from the first scan"',
     },
     {
         name: 'abap-upgrade-merge',
         category: 'Upgrade / Migrate',
         description: 'Reconcile multiple parallel /abap-upgrade-fix progress files into one consolidated upgrade-progress',
         whenToUse: 'pick this when a multi-dev team ran scoped fix slices in parallel — merges N progress files for /abap-upgrade-verify',
+        asks: 'which progress files. e.g. "merge the three @upgrade-progress files here"',
     },
     {
         name: 'abap-cca-merge',
         category: 'Upgrade / Migrate',
         description: 'Reconcile multiple parallel /abap-cca assessment files into one consolidated cca-assessment',
         whenToUse: 'pick this when multiple consultants ran scoped /abap-cca slices — merges N assessments into one team view',
+        asks: 'which assessments. e.g. "merge the ZFI and ZSD cca files"',
     },
     {
         name: 'abap-migrate',
         category: 'Upgrade / Migrate',
         description: 'ECC to S/4HANA migration assessment — API analysis, clean-core alignment, migration path',
         whenToUse: `pick this to pick retire/replace/refactor per object (not /abap-cca — cca discovers them)`,
+        asks: 'which objects. e.g. "package ZLEGACY, ECC to S/4"',
     },
     // ── Ship / Release ───────────────────────────────────────────────────────
     {
@@ -179,18 +205,21 @@ export const SKILL_CATALOG = [
         category: 'Ship / Release',
         description: 'Transport management — create, list, validate, release transport requests',
         whenToUse: `pick this to CREATE/LIST/RELEASE a TR (inspect-only? use /abap-transport-analysis)`,
+        asks: 'what to do. e.g. "create a transport for this session" or "release S4HK903449"',
     },
     {
         name: 'abap-transport-analysis',
         category: 'Ship / Release',
         description: 'Pre-release transport analysis — objects, ATC scan, activation status, conflict check',
         whenToUse: `pick this if you have a TR NUMBER and want a read-only safety scan`,
+        asks: 'which transport. e.g. "S4HK903449 before it goes to QA"',
     },
     {
         name: 'abap-preflight',
         category: 'Ship / Release',
         description: 'Pre-release checklist — ATC, syntax, inactive objects, transport conflicts',
         whenToUse: `pick this for a full ship-readiness package on a CHANGE SET (no TR# needed)`,
+        asks: 'what is going out. e.g. "the objects in S4HK903449"',
     },
     // ── Pre-Coding ───────────────────────────────────────────────────────────
     {
@@ -198,24 +227,28 @@ export const SKILL_CATALOG = [
         category: 'Pre-Coding',
         description: 'Find missing requirements before coding — business questions, technical gaps, assumptions',
         whenToUse: `pick this for missing business + technical questions on a vague spec (step 1 of 3 — feeds /abap-design)`,
+        asks: 'the requirement. e.g. paste the ticket text, or "@spec.pdf"',
     },
     {
         name: 'abap-design',
         category: 'Pre-Coding',
         description: 'Solution architecture — object list, dependency sequence, patterns, transport strategy. Plans the build, does not generate code.',
         whenToUse: `pick this for the object list + dependency sequence + pattern choices (step 2 of 3 — needs /abap-spec-gap done, feeds /abap-estimate or /abap-generate)`,
+        asks: 'the requirement, once the gaps are closed. e.g. "the inspection log from the spec above"',
     },
     {
         name: 'abap-estimate',
         category: 'Pre-Coding',
         description: 'Effort estimation for ABAP tickets — component breakdown with hour ranges (optimistic / realistic / pessimistic) + risk adjustments',
         whenToUse: `pick this for hour ranges + risk adjustments on a confirmed object list (step 3 of 3 — needs /abap-design first; high uncertainty without it)`,
+        asks: 'what to estimate. e.g. "the objects from the design above" or "all changes in this ticket"',
     },
     {
         name: 'abap-plan',
         category: 'Pre-Coding',
         description: 'Multi-session project plan — phase envelope holds state across sessions; create from a goal or spec-gap file, resume one bounded phase per session',
         whenToUse: `pick this when the work spans multiple sessions or components (not /abap-design — that's one design in one session; plan calls design per phase)`,
+        asks: 'the goal, or a plan to resume. e.g. "build the inspection log end to end"',
     },
 ];
 /**

package/dist/skills/bundled-skills.js

@@ -1,6 +1,6 @@
 // GENERATED FILE — bundled skills for local mode.
 // Source: https://manifest.cspeach.dev/v1.json
-// Generated: 2026-09-17T22:46:40.872Z
+// Generated: 2026-09-24T14:23:23.324Z
 // Manifest signature verified at build time.
 export const BUNDLED_SKILLS = {
     "abap-atc-fix": {

package/dist/tools/filesystem/extract-document.js

@@ -3,6 +3,7 @@
 import { extractText, getDocumentProxy } from 'unpdf';
 import mammoth from 'mammoth';
 import TurndownService from 'turndown';
+import { extractXlsx } from './extract-xlsx.js';
 /** Thrown when a PDF exceeds the caller's page ceiling — checked before full extraction. */
 export class DocumentTooLargeError extends Error {
     pages;
@@ -20,6 +21,11 @@ export async function extractDocument(buffer, ext, opts) {
         return extractPdf(buffer, opts?.maxPages);
     if (ext === '.docx')
         return extractDocx(buffer);
+    // 2026-09-23 — specs and object lists arrive as spreadsheets (Glenn).
+    if (ext === '.xlsx') {
+        const x = extractXlsx(buffer);
+        return { text: x.text, sheets: x.sheets, warnings: x.warnings };
+    }
     throw new Error(`extractDocument: unsupported extension "${ext}"`);
 }
 async function extractPdf(buffer, maxPages) {

package/dist/tools/filesystem/extract-xlsx.js

@@ -0,0 +1,139 @@
+/**
+ * .xlsx text extraction (2026-09-23 — Glenn: "it cannot read the excel file").
+ *
+ * Specs and object lists arrive as spreadsheets, so read_document reads them
+ * like any other document. An .xlsx IS a zip of XML parts, and adm-zip already
+ * ships inside the tree (SAP's own @sap-ux packages pull it), so nothing new
+ * enters the product to do this.
+ *
+ * Output shape: one "## Sheet: <name>" heading per sheet, then one line per
+ * row, cells separated by tabs, empty trailing cells dropped and empty leading
+ * ones kept so columns still line up. A model reads that as a table; a human
+ * reading the transcript can too.
+ *
+ * Deliberately NOT done: formulas (the cached VALUE is used, which is what the
+ * sheet shows), formatting, merged-cell geometry, charts, images. Dates come
+ * out as the serial number Excel stores unless the cell is text — the caller is
+ * told, rather than us guessing a locale.
+ */
+import AdmZip from 'adm-zip';
+/** Hard ceilings so one huge workbook cannot fill a turn. */
+export const MAX_SHEET_ROWS = 2000;
+export const MAX_CELLS = 100_000;
+const decode = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'").replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/&amp;/g, '&'); // last: an encoded "&amp;lt;" must not become "<"
+/** All <t> text inside one shared-string <si>, joined (rich text is split across runs). */
+function siText(si) {
+    const parts = [...si.matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((m) => decode(m[1]));
+    return parts.join('');
+}
+export function sharedStrings(xml) {
+    if (!xml)
+        return [];
+    return [...xml.matchAll(/<si>([\s\S]*?)<\/si>/g)].map((m) => siText(m[1]));
+}
+/** Column letters → 0-based index: A→0, B→1, AA→26. */
+export function colIndex(ref) {
+    const letters = /^([A-Z]+)/.exec(ref.toUpperCase())?.[1] ?? 'A';
+    let n = 0;
+    for (const ch of letters)
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    return n - 1;
+}
+/** One worksheet's cells as a rectangular grid of strings. */
+export function sheetRows(xml, strings, budget) {
+    const rows = [];
+    for (const rowMatch of xml.matchAll(/<row[^>]*>([\s\S]*?)<\/row>/g)) {
+        if (rows.length >= MAX_SHEET_ROWS || budget.cells <= 0)
+            break;
+        const cells = [];
+        for (const cell of rowMatch[1].matchAll(/<c\b([^>]*)>([\s\S]*?)<\/c>|<c\b([^>]*)\/>/g)) {
+            const attrs = cell[1] ?? cell[3] ?? '';
+            const body = cell[2] ?? '';
+            const at = colIndex(/r="([A-Z]+\d+)"/.exec(attrs)?.[1] ?? 'A1');
+            const type = /t="([^"]+)"/.exec(attrs)?.[1];
+            let value = '';
+            if (type === 's') {
+                const idx = Number(/<v>([\s\S]*?)<\/v>/.exec(body)?.[1] ?? '-1');
+                value = strings[idx] ?? '';
+            }
+            else if (type === 'inlineStr') {
+                value = siText(body);
+            }
+            else {
+                // n (number), str (formula result), b, d, e — the cached value as shown.
+                value = decode(/<v>([\s\S]*?)<\/v>/.exec(body)?.[1] ?? '');
+            }
+            while (cells.length < at)
+                cells.push('');
+            cells[at] = value.replace(/[\t\r\n]+/g, ' ').trim();
+            budget.cells -= 1;
+            if (budget.cells <= 0)
+                break;
+        }
+        while (cells.length > 0 && cells[cells.length - 1] === '')
+            cells.pop();
+        rows.push(cells);
+    }
+    while (rows.length > 0 && rows[rows.length - 1].length === 0)
+        rows.pop();
+    return rows;
+}
+/** Sheet name → part path, in the workbook's own order. */
+export function sheetOrder(workbookXml, relsXml) {
+    if (!workbookXml)
+        return [];
+    const rels = new Map();
+    for (const m of (relsXml ?? '').matchAll(/<Relationship\b([^>]*)\/>/g)) {
+        const id = /Id="([^"]+)"/.exec(m[1])?.[1];
+        const target = /Target="([^"]+)"/.exec(m[1])?.[1];
+        if (id && target)
+            rels.set(id, target.replace(/^\/?xl\//, '').replace(/^\//, ''));
+    }
+    const out = [];
+    for (const m of workbookXml.matchAll(/<sheet\b([^>]*)\/>/g)) {
+        const attrs = m[1];
+        const name = decode(/name="([^"]*)"/.exec(attrs)?.[1] ?? `Sheet${out.length + 1}`);
+        const rid = /r:id="([^"]+)"/.exec(attrs)?.[1] ?? '';
+        out.push({ name, path: `xl/${rels.get(rid) ?? `worksheets/sheet${out.length + 1}.xml`}` });
+    }
+    return out;
+}
+export function extractXlsx(buffer) {
+    let zip;
+    try {
+        zip = new AdmZip(buffer);
+    }
+    catch {
+        return { text: '', sheets: 0, warnings: ['not a readable .xlsx (the file may be .xls, password-protected or damaged)'] };
+    }
+    const read = (p) => {
+        const entry = zip.getEntry(p);
+        return entry ? entry.getData().toString('utf-8') : null;
+    };
+    const strings = sharedStrings(read('xl/sharedStrings.xml'));
+    const sheets = sheetOrder(read('xl/workbook.xml'), read('xl/_rels/workbook.xml.rels'));
+    if (sheets.length === 0) {
+        return { text: '', sheets: 0, warnings: ['no sheets found — the file may be .xls (old format); save it as .xlsx'] };
+    }
+    const budget = { cells: MAX_CELLS };
+    const warnings = [];
+    const blocks = [];
+    for (const s of sheets) {
+        const xml = read(s.path);
+        if (xml === null)
+            continue;
+        const rows = sheetRows(xml, strings, budget);
+        if (rows.length >= MAX_SHEET_ROWS)
+            warnings.push(`sheet "${s.name}" was cut at ${MAX_SHEET_ROWS} rows`);
+        blocks.push(`## Sheet: ${s.name}\n\n${rows.map((r) => r.join('\t')).join('\n')}`.trimEnd());
+    }
+    if (budget.cells <= 0)
+        warnings.push('the workbook was cut short — it holds more cells than one read returns');
+    const text = blocks.join('\n\n').trim();
+    if (text.length === 0)
+        warnings.push('no cell text found — the workbook may be empty or hold only charts/images');
+    return { text, sheets: sheets.length, warnings };
+}

package/dist/tools/filesystem/file-write.js

@@ -21,6 +21,25 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
 import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, blockedExecutableExtension, } from '../_filesystem-shared.js';
+/**
+ * 2026-09-23 (Glenn's first run) — a standalone run writes GUIDE.md and said
+ * nothing about it. He opened it in a text editor, then tried to drop it into
+ * an unrelated page on the site and got an error: "what does this file do …
+ * where would this enter back into the CSPEACH process?". Say it once, when
+ * the file appears, in the human stream.
+ */
+let guideNoteShown = false;
+export function __resetGuideNoteForTests() { guideNoteShown = false; }
+function noteGuideWritten(relPath, ctx) {
+    if (guideNoteShown)
+        return;
+    if (path.basename(relPath).toLowerCase() !== 'guide.md')
+        return;
+    guideNoteShown = true;
+    ctx.chunkEmitter?.emit('info', `${relPath} is your step-by-step list for applying these objects in SAP — `
+        + 'open it at https://cspeach.dev/guide, or in any text editor. '
+        + 'If a step fails, come back here and say "step N failed" with the error.');
+}
 export async function fileWriteHandler(args, ctx) {
     // 1. Path containment — sync phase (pure string math, catches .. traversals)
     let abs;
@@ -110,6 +129,7 @@ export async function fileWriteHandler(args, ctx) {
     }
     const relPath = path.relative(path.resolve(ctx.cwd), target).replace(/\\/g, '/');
     const bytes = Buffer.byteLength(args.content, 'utf-8');
+    noteGuideWritten(relPath, ctx);
     return { content: `wrote ${relPath} (${bytes} bytes)` };
 }
 registerTool({

package/dist/tools/filesystem/read-document.js

@@ -12,7 +12,7 @@ import { extractDocument, DocumentTooLargeError } from './extract-document.js';
 const MAX_LINES = 2000;
 const MAX_BYTES = 50 * 1024 * 1024; // 50 MB
 const MAX_PAGES = 150;
-const SUPPORTED = new Set(['.pdf', '.docx']);
+const SUPPORTED = new Set(['.pdf', '.docx', '.xlsx']);
 export async function readDocumentHandler(args, ctx) {
     if (args.offset !== undefined && args.offset < 0) {
         return { content: `error: offset must be non-negative (got ${args.offset})`, is_error: true };
@@ -32,7 +32,10 @@ export async function readDocumentHandler(args, ctx) {
     const ext = path.extname(abs).toLowerCase();
     if (!SUPPORTED.has(ext)) {
         return {
-            content: `error: read_document supports .pdf and .docx; convert "${args.path}" first (.doc/.pptx/scanned images are not supported)`,
+            content: ext === '.xls' || ext === '.csv'
+                ? `error: read_document reads .xlsx, not ${ext}; save "${args.path}" as .xlsx`
+                    + (ext === '.csv' ? ' — or read a .csv with file_read, it is plain text' : '')
+                : `error: read_document supports .pdf, .docx and .xlsx; convert "${args.path}" first (.doc/.pptx/scanned images are not supported)`,
             is_error: true,
         };
     }
@@ -74,8 +77,14 @@ export async function readDocumentHandler(args, ctx) {
         }
         return { content: `error: could not read "${args.path}": ${err instanceof Error ? err.message : String(err)}`, is_error: true };
     }
-    // 'document' is the intentional label for .docx: result.pages is PDF-only and undefined for Word files.
-    const header = `${args.path} — ${result.pages !== undefined ? `${result.pages} pages` : 'document'}`;
+    // 'document' is the intentional label for .docx: result.pages is PDF-only,
+    // result.sheets is .xlsx-only, and a Word file has neither.
+    const scale = result.pages !== undefined
+        ? `${result.pages} pages`
+        : result.sheets !== undefined
+            ? `${result.sheets} sheet${result.sheets === 1 ? '' : 's'}`
+            : 'document';
+    const header = `${args.path} — ${scale}`;
     const warnLines = result.warnings.map((w) => `[warning] ${w}`);
     const allLines = result.text.replace(/\n$/, '').split('\n');
     const offset = Math.max(0, args.offset ?? 0);
@@ -90,14 +99,14 @@ export async function readDocumentHandler(args, ctx) {
 }
 registerTool({
     name: 'read_document',
-    description: 'Read a .pdf or .docx and return its extracted text with page/heading markers and line numbers. Optional offset + limit for windowed reads of large documents.',
+    description: 'Read a .pdf, .docx or .xlsx and return its text with page/sheet/heading markers and line numbers. A spreadsheet comes back one sheet at a time, rows as tab-separated cells (cached values, not formulas). Optional offset + limit for windowed reads of large documents.',
     isMutating: false,
     category: 'filesystem',
     flagGated: true,
     input_schema: {
         type: 'object',
         properties: {
-            path: { type: 'string', description: 'Path to a .pdf or .docx, relative to the project root or absolute inside it.' },
+            path: { type: 'string', description: 'Path to a .pdf, .docx or .xlsx, relative to the project root or absolute inside it.' },
             offset: { type: 'number', description: 'Optional 0-based line offset into the extracted text.' },
             limit: { type: 'number', description: 'Optional max lines to return (cap 2000).' },
         },

package/dist/tools/include-snapshot.js

@@ -0,0 +1,24 @@
+/**
+ * Snapshot-store key for a class LOCAL INCLUDE (CCDEF / CCIMP / CCMAC / test
+ * classes). Pure — no fs, no SAP.
+ *
+ * Why a separate key (2026-09-21, found on the first clean-core fix): the
+ * include write used to snapshot the class MAIN source. For a RAP behaviour
+ * pool the main source is an 8-line shell and the change lives in CCIMP — so
+ * the Rule-7 backup never covered the change, and rewind wrote the unchanged
+ * main source back and reported success while the include change stayed.
+ *
+ * The include is stored under type `CLAS.<INCLUDE>` (e.g. `CLAS.LOCALS_IMP`),
+ * name = class name. A dot keeps the store's two-level type/name layout (no
+ * nested dirs) and can never collide with a real ABAP type code.
+ */
+const INCLUDE_TYPE_RE = /^CLAS\.(LOCALS_DEF|LOCALS_IMP|MACROS|TESTCLASSES)$/i;
+/** Snapshot type key for one include of a class. */
+export function includeSnapshotType(includeType) {
+    return `CLAS.${includeType.toUpperCase()}`;
+}
+/** The include a snapshot type key names, or null for an ordinary object type. */
+export function parseIncludeSnapshotType(type) {
+    const m = INCLUDE_TYPE_RE.exec(type);
+    return m ? m[1].toLowerCase() : null;
+}

package/dist/tools/sap-write.js

@@ -24,7 +24,8 @@
 import crypto from 'node:crypto';
 import { registerTool } from './index.js';
 import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
-import { autoSnapshot } from './snapshot.js';
+import { autoSnapshot, autoSnapshotClassInclude } from './snapshot.js';
+import { includeSnapshotType } from './include-snapshot.js';
 import { buildWriteChainLine } from '../renderer/verify-chain.js';
 import { verifySyntax, verifyActive } from './verify.js';
 import { appendPending, finalizeToolCall } from '../session/pending.js';
@@ -663,9 +664,9 @@ registerTool({
 // Writes a class local-include source (CCDEF/CCIMP/CCMAC/test classes). This is
 // how RAP behaviour-pool handlers (which live in CCIMP / locals_imp) get landed.
 // AdtClient locks the CLASS object, tries a ladder of PUT URL/content-type
-// variants (first 2xx wins), and always unlocks. Snapshot is best-effort:
-// the include source may not be independently readable, so a failed snapshot
-// must not block the write (consistent with sap_delete_object).
+// variants (first 2xx wins), and always unlocks. The Rule-7 snapshot is of the
+// INCLUDE itself (autoSnapshotClassInclude). It is non-blocking — a fresh
+// class's include may not be readable yet — but a failed one warns loudly.
 registerTool({
     name: 'sap_set_class_include',
     description: 'Write a class local-include source (CCDEF locals_def, CCIMP locals_imp, '
@@ -713,15 +714,24 @@ registerTool({
         // The CCIMP piece (LIMU CINC) is exactly the kind of object that sits
         // locked in a request from earlier work — battery S1's 409 root cause.
         const resolved = await resolveWriteTransport(ctx, 'CLAS', args.className, effectiveTransport);
-        // ── Gate 2: Snapshot (Rule 7) — best-effort, include may not be readable ─
+        // ── Gate 2: Snapshot (Rule 7) — of the INCLUDE being overwritten ─────────
+        // Not the class main source: for a behaviour pool that is an empty shell and
+        // the change lives in CCIMP (2026-09-21 — the old main-source snapshot left
+        // the change with no restore point, and rewind "restored" the wrong thing).
+        // Still non-blocking (a fresh class's include may not be readable yet), but
+        // a missing restore point is now said out loud instead of swallowed.
         let snapOutcome;
         try {
-            snapOutcome = await autoSnapshot(args.className, 'CLAS', ctx.adt);
+            snapOutcome = await autoSnapshotClassInclude(args.className, args.includeType, ctx.adt);
         }
-        catch {
-            // Silently ignore — include source may not be independently readable.
+        catch (err) {
+            snapOutcome = { taken: false, reason: 'source_read_failed', detail: String(err) };
+        }
+        emitSnapshotNotice(ctx, snapOutcome, includeSnapshotType(args.includeType), args.className);
+        if (snapOutcome?.reason === 'source_read_failed') {
+            ctx.chunkEmitter?.emit('warn', `CLAS ${args.className} ${args.includeType}: could not snapshot the include before writing `
+                + `(${snapOutcome.detail ?? 'read failed'}) — this write has NO restore point; rewind cannot undo it`);
         }
-        emitSnapshotNotice(ctx, snapOutcome, 'CLAS', args.className);
         // ── WAL: record pending entry ────────────────────────────────────────────
         await appendPending(ctx.session, {
             tool_use_id: toolUseId,

package/dist/tools/snapshot.js

@@ -15,6 +15,7 @@
  */
 import { registerTool } from './index.js';
 import { snapshots, SapError } from '@cspeach/sap-client';
+import { includeSnapshotType } from './include-snapshot.js';
 /** True only for a genuine ADT 404 — the object does not exist. Any other
  *  failure (network, auth, 5xx, timeout) is a READ failure, not proof of
  *  absence, and must never be labelled "object not found". */
@@ -100,6 +101,32 @@ export async function autoSnapshot(objectName, objectType, adt) {
     const entry = await snapshots.take(objectType, objectName, src, 'before_write');
     return { taken: true, entry };
 }
+/**
+ * Rule-7 snapshot of ONE class local include, taken before sap_set_class_include
+ * overwrites it. Stored under includeSnapshotType(includeType) + class name so
+ * rewind can put the include (not the class main source) back.
+ *
+ *   404               → 'object_not_found' (include has no source yet — nothing to protect)
+ *   other read error  → 'source_read_failed' (+ detail) — caller decides; no restore point
+ *   read OK (even '') → snapshot taken
+ * A snapshots.take failure THROWS, like autoSnapshot.
+ */
+export async function autoSnapshotClassInclude(className, includeType, adt) {
+    let src;
+    try {
+        src = await adt.classIncludes(className, includeType);
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { taken: false, reason: 'object_not_found' };
+        return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+    }
+    if (typeof src !== 'string') {
+        return { taken: false, reason: 'source_read_failed', detail: 'include read returned no source text' };
+    }
+    const entry = await snapshots.take(includeSnapshotType(includeType), className, src, 'before_write');
+    return { taken: true, entry };
+}
 // ── sap_snapshot_list ─────────────────────────────────────────────────────────
 registerTool({
     name: 'sap_snapshot_list',