tadforce 0.3.0 → 0.4.1

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "tadforce",
       "source": "./",
       "description": "AI-Powered Salesforce Technical Documentation: generate, review, validate and update the Technical Architecture Document of any Salesforce org (/tadforce, /tadforce-review, /tadforce-update).",
-      "version": "0.3.0",
+      "version": "0.4.1",
       "author": { "name": "Jihad AZAMI HASSANI" },
       "license": "Apache-2.0",
       "category": "documentation"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tadforce",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AI-Powered Salesforce Technical Documentation — the Technical Architecture Document of any Salesforce org, written from the org's own metadata: evidence-based, reproducible, reviewable in the browser, kept up to date. All Salesforce products and industries.",
   "author": {
     "name": "Jihad AZAMI HASSANI",

package/README.md

@@ -47,11 +47,9 @@ From your Salesforce DX project (or an empty folder):
 npx tadforce doctor
 ```
 
-Then, in your AI agent (Claude Code, Codex, Cursor, Copilot…):
+That one command installs everything: it downloads TADForce, installs the agent skills in your project, connects to the org, collects the metadata and asks you the few questions only a human can answer. When everything is green, it says so and **offers to hand over to your AI agent** (Claude Code, Codex, Gemini CLI or Cursor, detected on your machine), which writes, builds and validates the document — nothing else to type.
 
-```text
-/tadforce
-```
+Already in your agent? Type `/tadforce`: it runs the same checks, then writes.
 
 <table>
 <tr><th width="33%">A — Claude Code plugin</th><th width="33%">B — Any agent (Agent Skills)</th><th width="33%">C — Deterministic / CI</th></tr>
@@ -134,7 +132,7 @@ The document carries **the client's logo and colours**: the logo is searched in
 
 | Your situation | How TADForce handles it |
 |---|---|
-| **A whole org**, as-built | `doctor` retrieves everything with a curated `*` manifest (130 types, foldered reports and dashboards, standard objects) |
+| **A whole org**, as-built | `doctor` retrieves everything with a curated `*` manifest (105 types — only what the document uses, foldered reports and dashboards, standard objects) |
 | **One project in a shared org** (several BUs, several integrators) | Scope: `--scope "NWB_*,Loan*"` or `--package-dirs`. Out-of-scope components leave facts, counts and tables; standard objects and org-wide settings stay |
 | **Before or during the build** | Give your functional specifications (`--specs SFD.pdf,…`): they become evidence (level P2/P3) next to the metadata |
 | **No org access**, sources only | `--source local` documents the package directories of the project |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tadforce",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AI-Powered Salesforce Technical Documentation — the Technical Architecture Document of any Salesforce org, written from the org's own metadata: evidence-based, reproducible, reviewable in the browser, kept up to date.",
   "type": "module",
   "bin": {

package/skills/tadforce/references/questions.md

@@ -4,23 +4,22 @@ Ask in **blocks**, each in one message, with your proposed answer for every item
 
 ## Block A — startup (before or right after authorization)
 
-`npx tadforce doctor --json` returns these questions with a `recommended` answer each (from the org when connected). Ask them all in one message:
+`npx tadforce doctor --json` asks, in this order and one step at a time: the **project** (is this the Salesforce project to document?), the **org** (is this the org?), then these framing questions — six, each with a `recommended` answer. Ask them all in one message and let the human accept them all at once:
 
 1. Document language — recommended: the org default language. English and French are built in; any other language works (the headings and labels are translated once, see `workflow.md › Other languages`).
-2. Client name and short code (file names) — recommended: `Organization.Name` / `<CODE>`.
-3. Integrator — **optional**. Blank: the document names the client only (no empty « Integrator » line, no badge).
+2. Client name, as it must appear in the document — recommended: `Organization.Name`. The short code (file names) and the reference are derived from it.
+3. Integrator — **optional**. Blank: the document names the client only (no empty « Integrator » line, no badge). The Improvement Axes then carry the client's brand.
 4. Author — **optional**. Blank: no author is shown anywhere. Never put your own name or the agent's.
-5. Document title — recommended: « Salesforce CRM Platform » (or the client's name for the solution).
+5. Functional specifications — **optional**: paths to PDF / DOCX / MD files (copied into `knowledge/inputs/specs/`).
 6. Scope — **optional**: name patterns of the components the project owns (`NWB_*,Loan*`), when the org is shared with other teams. Blank: the whole org.
-7. Client logo — **optional**: a file or a URL. Blank: TADForce searches the org (static resources, content assets, site assets), then falls back to an initials badge. The document colours follow the org's Lightning theme, else the logo. If none is found and the client has a public website, you may *offer* to look for the logo there — fetch it only after the human says yes.
-8. Functional specifications — **optional**: paths to PDF / DOCX / MD files (copied into `knowledge/inputs/specs/`).
-9. Metadata — `org` (recommended: retrieve everything from the org), `local` (the sources of this project), or `both`.
 
-Answer with `npx tadforce doctor --json --confirm --lang fr --client "…" --short ABC --integrator none --author "…" --title "…" [--scope "…"] [--logo …] [--specs … | --no-specs] [--source org]`.
+Answer with `npx tadforce doctor --json --confirm --lang fr --client "…" --integrator none --author none [--specs … | --no-specs] [--scope "…"]`. The title stays « Salesforce CRM Platform » unless the human gives one (`--title`).
+
+Then come the metadata choice (`source`, which is also the go for the retrieve), the **branding** (logo and colours found in the org — never fetch a logo from the web without the human's go-ahead), and Blocks B to D.
 
 FR example:
 
-> Pour démarrer, je propose : langue **français** (langue par défaut de l'org : fr_FR) · client **« Banque Exemple »** (code `BEX`) · intégrateur : **aucun** · auteur : **aucun** · titre **« Plateforme CRM Salesforce »** · périmètre : **toute l'org** · logo : **cherché dans l'org** · spécifications fonctionnelles : **aucune** · métadonnées : **depuis l'org**. Je confirme ? Indiquez seulement ce qui change.
+> Pour démarrer, je propose : langue **français** (langue par défaut de l'org : fr_FR) · client **« Banque Exemple »** · intégrateur : **aucun** · auteur : **aucun** · spécifications fonctionnelles : **aucune** · périmètre : **toute l'org**. Je valide tout ? Indiquez seulement ce qui change.
 
 ## Block B — external systems (from `facts/questions.json › systems`)
 

package/skills/tadforce/references/workflow.md

@@ -13,27 +13,33 @@ npx tadforce doctor --json
 | `next` says | You do |
 |---|---|
 | install the missing tools | `sf-cli` missing: you may run `npm install --global @salesforce/cli` after asking. Node or a browser missing: human action (or `npx @puppeteer/browsers install chrome-headless-shell@stable` + `TADFORCE_CHROME`) |
-| the human logs in | No org, or an expired session. Ask the human to run `npx tadforce doctor` in a terminal (it opens the browser) or `sf org login web --alias <a> --set-default [--instance-url https://test.salesforce.com]`. No org at all: `--source local` documents the local sources |
-| ask the human these questions | Block A of `questions.md`: one message, a recommendation for each. Then `npx tadforce doctor --json --confirm --lang fr --client "…" --short ABC --integrator "…"\|none --author "…"\|none --title "…" [--scope "NWB_*,Loan*"] [--logo <file\|url>] [--specs a.pdf,b.docx \| --no-specs] [--source org\|local\|both]` |
-| write the answers to the knowledge files | Blocks B, C and D of `questions.md` → `knowledge/glossary.yml`, `knowledge/exclusions.yml`; then `npx tadforce facts` and `npx tadforce doctor --json --facts-reviewed` |
+| question `project` | Confirm with the human that this Salesforce project is the one to document → `--project yes`. Not in a project: `doctor` creates nothing; it proposes the projects found nearby → `--project <path>` (then always pass `--cwd <path>`), or `--project create` only if the human asks for a new project here |
+| question `org` | Show the org (alias, user, URL) and ask whether the TAD is about it → `--org <alias>`. Another org, or none connected: the human logs in (`sf org login web --alias <a> [--instance-url https://test.salesforce.com]`, it opens the browser), then ask again and pass `--org <a>`. No org at all: `--source local` |
+| framing questions | Block A of `questions.md`: one message, the recommended answer for each, « accept all » allowed → `--confirm --lang … --client "…" --integrator …|none --author …|none [--specs …|--no-specs] [--scope …]` |
+| question `source` | org (retrieve everything, read-only, several minutes), local, or self (the human retrieves first). The answer **is the go**: ask before passing `--source org` — the retrieve starts right away. `self`: wait until the human says the retrieve is done, then `--source local` |
+| question `branding` | Show the logo and colours found → `--branding keep`, or `--logo <file|url>` |
+| systems / exclusions / features | Blocks B, C and D of `questions.md`, recommended answers shown → write `knowledge/*.yml`, then `--facts-reviewed` (it recomputes the facts with your answers) |
 | `tadforce build` | Ready: write and build |
 
+Run by a person in a terminal, a green `doctor` starts the AI agent found on the machine on `/tadforce` (`--agent claude|codex|gemini|cursor`, `--no-launch` to stop there). Run by you (`--json`, or inside an agent session), it never starts another agent: carry on with the writing.
+
 What `doctor` does by itself, read-only:
 
 - creates the SFDX project and the `tadforce/` workspace if missing, installs the skills for the agents found;
 - reuses the project's `target-org` (`sf config get target-org`) — no separate login step when the project already has one;
-- metadata, as chosen (`source`): **org** (recommended — the org is the truth) retrieves every useful type with a `*` manifest into `tadforce/.snapshot` (`force-app` is never touched; large orgs take several minutes: tell the human); **local** reads the package directories; **both** combines them. Then `facts/facts.json`, `facts/org.json` (aggregates), `facts/questions.json`, the chapter skeletons in `tadforce/src/`;
+- metadata, as chosen (`source`): **org** (recommended — the org is the truth) retrieves every useful type with a `*` manifest into `tadforce/.snapshot` (`force-app` is never touched; a large org takes 10 to 20 minutes — tell the human before, and follow the progress printed on stderr); **local** reads the package directories; **both** combines them. Then `facts/facts.json`, `facts/org.json` (aggregates), `facts/questions.json`, the chapter skeletons in `tadforce/src/`;
 - branding from evidence: the client logo searched in the snapshot (static resources, content assets, site assets named *logo*), the colours from the org's Lightning theme (`BrandingSet`), else from the logo. Never fetch a logo from the web without the human's go-ahead; when they agree, pass its URL with `--logo`.
 
 ### Other languages
 
 English and French are built in. Any other language (`--lang es`, `de`, `it`, `pt`, `nl`, `ar`, `ja`…) works too: the skeletons are scaffolded in English and `tadforce/i18n/<lang>.json` is created from the English labels. Once, before writing:
 
-1. Translate the headings of every `tadforce/src/*/*.md` file into the document language. Keep the `{#anchors}`, the `{-}` markers, the `<!-- tad:… -->` lines and the `@@…@@` directives exactly as they are.
+1. Translate the headings **and the body text** of every `tadforce/src/*/*.md` file (chapter 2 and the axes method hold ready-made paragraphs). Keep the `{#anchors}`, the `{-}` markers, the `<!-- tad:… -->` lines and the `@@…@@` directives as they are — except the caption after `|` in a directive (`@@ERD:A,B|caption@@`), which you translate.
 2. Translate every value of `tadforce/i18n/<lang>.json` (cover, tables, figures, buttons of the HTML). Keep the keys and the `{placeholders}`; set `meta.htmlLang`. Delete the `_translate` line.
-3. Write the sections in that language; Salesforce terms stay in English.
+3. Translate `document.title`, `status`, `classification` and `environment` in `tadforce/tadforce.config.json` (their defaults are English).
+4. Write the sections in that language; Salesforce terms and metadata values stay as they are. Dates and numbers follow the language by themselves.
 
-`doctor` shows a reminder until step 2 is done. To ship the language for everyone, contribute it (issue template « New language »).
+Batch it: one script or one file write per kind (headings map, labels file), not one edit per heading. `doctor` shows a reminder while the labels file or chapters with English headings remain. To ship the language for everyone, contribute it (issue template « New language »).
 
 ### Optional inputs
 

package/skills/tadforce-review/SKILL.md

@@ -42,6 +42,8 @@ When the comment contradicts the metadata, do not silently obey: answer with the
    - add ids to `dropImages` when a capture is no longer useful (keeps the file small).
 4. `npx tadforce build --pdf --docx` — handled comments appear as **resolved**, with your answer, in the panel of the same HTML file. When the readers also edited text in the page, the build keeps a copy (`…_comments_<date>.html`): report those edits into the sources.
 
+A comment a reader reopened after its resolution stays open at the next build (warning `comment-reopened`): read the new remark and answer it again with a new resolution.
+
 ## 4. Report
 
 One line per comment: id, section, what changed (or why not). Then the validation score. Ask the human to reopen the new HTML and check the resolved comments.

package/skills/tadforce-update/SKILL.md

@@ -13,14 +13,14 @@ The document already exists. Do not rewrite it: find what changed, and rewrite o
 npx tadforce update --json
 ```
 
-It archives the previous facts (`tadforce/facts/history/<date>/`), retrieves a fresh snapshot (`source.mode`), recomputes the facts, compares content fingerprints and returns:
+It retrieves a fresh snapshot (`source.mode`), recomputes the facts, compares content fingerprints and returns:
 
 - `changes.added | changed | removed` — components, by metadata folder (`classes:InvoiceService`, `flows:Case_Routing`…);
 - `counts` — every count that moved (`apex.classes: [132, 140]`);
-- `sections[]` — the sections to review: `id`, `file`, `anchor` (the heading `{#id}` the section sits under) and the `reasons`;
-- `from` → `to` — the version bump, already written to the document history.
+- `sections[]` — the written sections to review: `id`, `file`, `anchor` (the heading `{#id}` the section sits under), `reasons` and `relevance`: **components** (a component it describes was added, changed or removed: rewrite) or **counts** (only numbers moved: check that the text states no number the facts now contradict). Sections still to write are not listed;
+- `from` → `to` — the version bump, already written to the document history (the facts of `from` are archived in `facts/history/v<from>/`, never overwritten).
 
-Nothing changed: say so and stop.
+`upToDate: true`: nothing changed — say so and stop.
 
 ## 2. Ask, once
 
@@ -39,6 +39,8 @@ A section listed only for moved counts usually needs no change: check that the t
 
 Then, in chapter 15 (Outlook) or the Improvement Axes, record what the update revealed that the client should know (new debt goes to the Axes, never to the TAD).
 
+Comments answered before the update (`review.tad.resolutions`) may no longer be true: re-read each one against the new behaviour and correct its answer.
+
 ## 4. Build and report
 
 ```bash

package/src/build/directives.js

@@ -1,6 +1,6 @@
 // Deterministic content generated from facts: appendices, ERDs, figures, KPI tiles, placeholders.
 import path from 'node:path';
-import { t, formatNumber } from '../util/i18n.js';
+import { t, formatNumber, formatDate } from '../util/i18n.js';
 import { exists, readText } from '../util/fsx.js';
 import { contextView, layersBlock } from './figures.js';
 
@@ -57,7 +57,11 @@ export function resolveValues(text, ctx, problems) {
     const src = kind === 'cfg' ? ctx.cfg : ctx.facts;
     let v = kind === 'n' ? (get(ctx.facts.counts, p) ?? get(ctx.facts, p)) : get(src, p);
     if (kind === 'n' && Array.isArray(v)) v = v.length;
-    if (v === undefined || v === null) { problems.push({ level: 'error', code: 'unknown-placeholder', message: `Unknown placeholder ${m}` }); return `⟨${m.slice(2, -2)}⟩`; }
+    if (v === undefined || v === null || v === '') {
+      problems.push({ level: 'error', code: 'unknown-placeholder', message: kind === 'cfg' && get(ctx.cfg, p) !== undefined ? `${m} is empty in tadforce.config.json: fill it, or put the sentence inside <!-- tad:if cfg.${p} -->` : `Unknown placeholder ${m}` });
+      return `⟨${m.slice(2, -2)}⟩`;
+    }
+    if (kind === 'cfg' && /date$/i.test(p)) return formatDate(v, ctx.lang);
     return kind === 'n' && typeof v === 'number' ? formatNumber(v, ctx.lang) : String(v);
   });
 }
@@ -78,14 +82,14 @@ function annexes(ctx) {
       ...(cfg.integrator.name ? [[t(dict, 'control.integrator'), cfg.integrator.name]] : []),
       ...(cfg.document.author ? [[t(dict, 'control.preparedBy'), cfg.document.author]] : []),
       [t(dict, 'control.version'), `${cfg.document.version}${cfg.document.status ? ' — ' + cfg.document.status : ''}`],
-      [t(dict, 'control.date'), cfg.document.date],
-      [t(dict, 'control.classification'), cfg.document.classification],
-      [t(dict, 'control.scope'), t(dict, 'control.scopeValue', { environment: cfg.document.environment, client: cfg.client.name, date: cfg.document.date })
-        + (cfg.scope && (cfg.scope.include || []).length ? ' — ' + t(dict, 'control.scopeLimited', { scope: cfg.scope.include.map((x) => '`' + x + '`').join(', ') }) : '')],
+      [t(dict, 'control.date'), formatDate(cfg.document.date, ctx.lang)],
+      [t(dict, 'control.classification'), ctx.doc === 'axes' ? t(dict, 'doc.axesKicker') : cfg.document.classification],
+      [t(dict, 'control.scope'), t(dict, cfg.source && cfg.source.mode === 'local' ? 'control.scopeValueLocal' : 'control.scopeValue', { environment: cfg.document.environment, client: cfg.client.name, date: formatDate(cfg.document.date, ctx.lang) })
+        + (cfg.scope && (cfg.scope.include || []).length ? ' — ' + t(dict, 'control.scopeLimited', { scope: cfg.scope.label || cfg.scope.include.join(', ') }) : '')],
     ]),
     'version-history': () => mdTable([t(dict, 'control.version'), t(dict, 'control.date'), t(dict, 'control.author'), t(dict, 'control.purpose')],
-      (cfg.document.history && cfg.document.history.length ? cfg.document.history : [{ version: cfg.document.version, date: cfg.document.date, author: [cfg.document.author, cfg.integrator.name].filter(Boolean).join(' — ') || cfg.client.name, purpose: t(dict, 'control.firstVersion', { client: cfg.client.name }) }])
-        .map((h) => [h.version, h.date, h.author, h.purpose])),
+      (cfg.document.history && cfg.document.history.length ? cfg.document.history : [{ version: cfg.document.version, date: cfg.document.date, author: [cfg.document.author, cfg.integrator.name].filter(Boolean).join(' — ') || '—', purpose: t(dict, 'control.firstVersion', { client: cfg.client.name }) }])
+        .map((h) => [h.version, formatDate(h.date, ctx.lang), h.author || '—', h.purpose])),
     legend: () => `<div class="legend">\n<span class="lg actor">${t(dict, 'legend.actor')}</span>\n<span class="lg sf">${t(dict, 'legend.sf')}</span>\n<span class="lg ext">${t(dict, 'legend.ext')}</span>\n<span class="lg data">${t(dict, 'legend.data')}</span>\n</div>`,
     'key-figures': () => mdTable([A('domain'), A('count')], [
       [t(dict, 'keyfig.apps'), n(f.counts.ui.apps)], [t(dict, 'keyfig.pages'), n(f.counts.ui.flexipages)], [t(dict, 'keyfig.lwc'), n(f.counts.ui.lwc)],
@@ -193,7 +197,8 @@ export function erd(facts, objectNames, caption) {
   if (names.length === 1 && names[0] === 'auto') {
     const degree = {};
     for (const o of facts.data.objects.filter((x) => !x.namespace)) {
-      for (const r of o.relations) for (const to of r.to) { if (to === o.name || to === 'User' || to === 'Group') continue; degree[o.name] = (degree[o.name] || 0) + 1; degree[to] = (degree[to] || 0) + 1; }
+      // only objects documented here: an out-of-scope or excluded target never becomes a box
+      for (const r of o.relations) for (const to of r.to) { if (to === o.name || to === 'User' || to === 'Group' || !byName.has(to)) continue; degree[o.name] = (degree[o.name] || 0) + 1; degree[to] = (degree[to] || 0) + 1; }
     }
     names = Object.entries(degree).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 12).map(([k]) => k);
   }
@@ -282,8 +287,8 @@ export function resolveDirectives(text, ctx, problems) {
     if (kind === 'FIGURE') {
       if (arg === 'context') return '<div class="fig-body hand">' + contextView(ctx.facts, ctx.glossary, ctx.cfg, ctx.dict) + '</div>\n<p class="figcap">Figure — ' + (caption || t(ctx.dict, 'context.caption')) + '</p>';
       if (arg === 'layers') return layersBlock(ctx.facts, ctx.dict);
-      if (arg === 'roles') return rolesFigure(ctx.facts, caption || 'Role hierarchy');
-      if (arg === 'integrations') return integrationsFigure(ctx.facts, ctx.cfg, ctx.dict, caption || 'Integration map');
+      if (arg === 'roles') return rolesFigure(ctx.facts, caption || t(ctx.dict, 'figures.roles'));
+      if (arg === 'integrations') return integrationsFigure(ctx.facts, ctx.cfg, ctx.dict, caption || t(ctx.dict, 'figures.integrations'));
       problems.push({ level: 'error', code: 'unknown-figure', message: `Unknown figure @@FIGURE:${arg}@@` });
       return '';
     }

package/src/build/figures.js

@@ -115,5 +115,5 @@ export function layersBlock(facts, dict) {
   const svc = [c.apex.triggers && L('triggers', c.apex.triggers), c.apex.auraEnabled && L('controllers', c.apex.auraEnabled), L('services', c.apex.classes), (c.apex.batch + c.apex.queueable + c.apex.schedulable + c.apex.future) && L('async')];
   const data = [L('standard'), c.objects.custom && L('custom', c.objects.custom), c.cmdt.types && L('cmdt', c.cmdt.types), L('files')];
   const integ = [c.integration.namedCredentials && L('nc', c.integration.namedCredentials), c.integration.externalCredentials && L('ec', c.integration.externalCredentials), c.integration.restResources && L('rest', c.integration.restResources), c.integration.connectedApps && L('apps2', c.integration.connectedApps)];
-  return `<div class="layers">\n${row('', L('presentation'), pres)}\n${row('', L('orchestration'), orch.length && orch.some(Boolean) ? orch : ['—'])}\n${row('', L('services'), svc)}\n${row('data', L('data'), data)}\n${row('int', L('integration'), integ.some(Boolean) ? integ : ['—'])}\n</div>\n<p class="figcap">Figure — ${esc(L('caption'))}</p>`;
+  return `<div class="layers">\n${row('', L('presentation'), pres)}\n${row('', L('orchestration'), orch.length && orch.some(Boolean) ? orch : ['—'])}\n${row('', L('servicesTitle'), svc)}\n${row('data', L('data'), data)}\n${row('int', L('integration'), integ.some(Boolean) ? integ : ['—'])}\n</div>\n<p class="figcap">Figure — ${esc(L('caption'))}</p>`;
 }

package/src/build/render.js

@@ -3,8 +3,9 @@ import path from 'node:path';
 import MarkdownIt from 'markdown-it';
 import { exists, readText, writeText, readJson } from '../util/fsx.js';
 import { TEMPLATES, PKG_ROOT } from '../util/paths.js';
-import { loadI18n, t } from '../util/i18n.js';
+import { loadI18n, t, formatDate } from '../util/i18n.js';
 import { loadFacts } from '../facts/index.js';
+import { sourceFlags } from '../util/config.js';
 import { CLASSDEFS, renderMermaid, escapeHtml } from './mermaid.js';
 import { resolveConditionals, resolveIncludes, resolveDirectives, resolveValues } from './directives.js';
 
@@ -115,7 +116,7 @@ export async function buildDocument(wsCtx, doc, opts = {}) {
   if (!files.length) throw new Error(`No Markdown chapters in ${srcDir}.`);
 
   let text = files.map((f) => readText(path.join(srcDir, f))).join('\n\n');
-  const scope = { modules: facts.modules, counts: facts.counts, org: facts.org, cfg, facts, glossary };
+  const scope = { modules: facts.modules, counts: facts.counts, org: facts.org, cfg, facts, glossary, source: sourceFlags(cfg) };
   const docName = doc === 'tad' ? t(dict, 'meta.docName') : t(dict, 'meta.axesName');
   const ctx = { facts, cfg, dict, lang, glossary, doc, docName, chapterTitle: (k) => `{{title:ch-${k}}}` };
   text = resolveConditionals(text, scope);
@@ -221,7 +222,7 @@ export async function buildDocument(wsCtx, doc, opts = {}) {
     '{{DOC_SUBTITLE}}': escapeHtml(cfg.document.subtitle || [cfg.client.name, ...facts.modules.clouds.filter((x) => !['events', 'shield', 'slack'].includes(x.id)).slice(0, 3).map((x) => x.name)].join(' · ')),
     '{{DOC_REFERENCE}}': escapeHtml(doc === 'tad' ? cfg.document.reference : cfg.document.reference + '-AX'),
     '{{DOC_VERSION}}': escapeHtml(`${cfg.document.version}${cfg.document.status ? ' — ' + cfg.document.status : ''}`),
-    '{{DOC_DATE}}': escapeHtml(cfg.document.date),
+    '{{DOC_DATE}}': escapeHtml(formatDate(cfg.document.date, lang)),
     '{{DOC_CLASSIFICATION}}': escapeHtml(doc === 'tad' ? cfg.document.classification : t(dict, 'doc.axesKicker')),
     '{{INTEGRATOR_NAME}}': escapeHtml(integrator || cfg.client.name),
     '{{COVER_LOGOS}}': coverLogos,
@@ -233,7 +234,7 @@ export async function buildDocument(wsCtx, doc, opts = {}) {
     '{{INTEGRATOR_LOGO}}': sideLogo,
     '{{CLIENT_LOGO}}': logo('client'),
     '{{SIDE_TITLE}}': escapeHtml(`${docName} — ${cfg.document.title}`),
-    '{{SIDE_SUB}}': escapeHtml(`${cfg.client.name} · v${cfg.document.version} · ${cfg.document.date}`),
+    '{{SIDE_SUB}}': escapeHtml(`${cfg.client.name} · v${cfg.document.version} · ${formatDate(cfg.document.date, lang)}`),
     '{{FOOTER}}': escapeHtml(`${integrator ? integrator + ' · ' : ''}${internal ? '' : cfg.client.name + ' · '}${doc === 'tad' ? cfg.document.classification : t(dict, 'doc.axesKicker')}`) + ` · <span class="gen">${escapeHtml(t(dict, 'doc.generatedBy'))}</span>`,
     '{{I18N_JSON}}': JSON.stringify({ editor: dict.editor }).replace(/</g, '\\u003c'),
     '{{BRAND_JSON}}': JSON.stringify(brand).replace(/</g, '\\u003c'),
@@ -271,7 +272,9 @@ export async function buildDocument(wsCtx, doc, opts = {}) {
   for (const c of carried) {
     if (c.status === 'résolu') c.status = 'resolved';
     const res = review.resolutions && review.resolutions[c.id];
-    if (res) { c.status = 'resolved'; c.response = res; }
+    // already answered with this resolution, yet open again: a reader reopened it — keep it open
+    if (res && c.status === 'open' && c.response === res) problems.push({ level: 'warn', code: 'comment-reopened', message: `Comment ${c.id} was reopened by a reader after its resolution: answer it again (review.${doc}.resolutions).` });
+    else if (res) { c.status = 'resolved'; c.response = res; }
     if ((review.dropImages || []).includes(c.id)) c.image = null;
   }
   if (carried.length) {

package/src/commands/docs.js

@@ -2,7 +2,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { exists, writeJson, readText, copyDir, stableStringify } from '../util/fsx.js';
-import { loadWorkspace, sourceDirs } from '../util/config.js';
+import { loadWorkspace, sourceDirs, sourceFlags } from '../util/config.js';
+import { resolveConditionals } from '../build/directives.js';
 import { TEMPLATES } from '../util/paths.js';
 import { LANGUAGES, normalizeLang, templateLang } from '../util/i18n.js';
 import { extractFacts, readCodeAnalyzer, loadFacts } from '../facts/index.js';
@@ -12,14 +13,17 @@ import { buildDocument, readComments, outputName, DOCS } from '../build/render.j
 import { exportPdf, exportDocx } from '../build/export.js';
 import { closeBrowser } from '../build/browser.js';
 import { validateDocument } from '../validate/index.js';
-import { log, c } from '../util/log.js';
+import { log, c, setQuiet } from '../util/log.js';
 import * as org from './org.js';
 
 const docsOf = (args) => (!args.doc || args.doc === 'all' ? DOCS : String(args.doc).split(','));
 
 export async function facts(args) {
   const ctx = loadWorkspace(args.cwd || process.cwd());
-  const dirs = args.source ? [path.resolve(args.source)] : sourceDirs(ctx);
+  if (args.json) setQuiet(true); // stdout carries the JSON only
+  // --source names a folder: one that does not exist is an error, never an empty inventory
+  if (typeof args.source === 'string' && !exists(path.resolve(args.source))) throw new Error(`--source: no such folder ${path.resolve(args.source)} (use the folder that holds the metadata, e.g. force-app).`);
+  const dirs = typeof args.source === 'string' ? [path.resolve(args.source)] : sourceDirs(ctx);
   if (!dirs.length) throw new Error('No metadata found: run `tadforce retrieve` (or point --source at a force-app folder).');
   log.banner('facts');
   log.step(`Reading metadata from ${dirs.map((d) => path.relative(ctx.project, d) || '.').join(', ')}`);
@@ -41,6 +45,8 @@ export async function facts(args) {
   const questions = buildQuestions(f, orgFacts);
   writeJson(ctx.p('facts', 'questions.json'), questions);
   const k = f.counts;
+  if (args.json) { console.log(JSON.stringify({ components: f.inventory.length, counts: k, modules: f.modules.products, sources: f.sources, questions: { systems: questions.systems.length, exclusions: questions.exclusions.total } }, null, 2)); return f.inventory.length ? 0 : 1; }
+  if (!f.inventory.length) log.warn(`No component found in ${dirs.map((d) => path.relative(ctx.project, d) || '.').join(', ')}: is the metadata there?`);
   log.ok(`facts.json: ${k.apex.classes} classes (+${k.apex.tests} tests), ${k.apex.triggers} triggers, ${k.flows.active} active flows, ${k.ui.lwc} LWC, ${k.objects.custom} custom objects, ${k.security.permissionSetGroups} PSG`);
   log.info(`modules: ${Object.entries(f.modules).filter(([kk, v]) => v === true).map(([kk]) => kk).join(', ') || 'none'}${f.modules.products.length ? ' · products: ' + f.modules.products.join(', ') : ''}`);
   if (questions.systems.length) log.human(`${questions.systems.length} external endpoint(s) need a system name → knowledge/glossary.yml (see facts/questions.json).`);
@@ -52,7 +58,7 @@ export async function facts(args) {
 export function buildQuestions(f, orgFacts) {
   const byReason = {};
   for (const cnd of f.exclusions.candidates) {
-    const key = cnd.reasons[0].replace(/name suggests .*/, 'name suggests test / demo / POC / sample');
+    const key = cnd.reasons[0].replace(/name suggests .*/, 'name suggests an unused component (test, demo, POC, sample, old, legacy…)');
     (byReason[key] ||= []).push(`${cnd.type}:${cnd.name}`);
   }
   if (orgFacts && orgFacts.volumes) {
@@ -116,8 +122,10 @@ export async function build(args) {
       built.push(r);
       if (r.pending.length) log.warn(`${r.pending.length} section(s) of ${doc} still to write — your agent writes them (tadforce next), then build again.`);
       log.ok(`${path.relative(ctx.project, r.html)} (${r.sizeKB} KB, ${r.figures} figures)`);
-      const wantPdf = args.pdf ?? ctx.cfg.outputs.pdf;
-      const wantDocx = args.docx ?? ctx.cfg.outputs.docx;
+      // naming one format (--pdf) means that one only; with no flag, the config decides
+      const named = args.pdf !== undefined || args.docx !== undefined;
+      const wantPdf = named ? args.pdf === true : ctx.cfg.outputs.pdf;
+      const wantDocx = named ? args.docx === true : ctx.cfg.outputs.docx;
       const archive = path.join(path.dirname(r.html), outputName(ctx.cfg, doc, { versioned: true }));
       if (wantPdf && args.render !== false) { const p = archive + '.pdf'; const s = await exportPdf(r.html, p); log.ok(`${path.relative(ctx.project, p)} (${Math.round(s / 1024)} KB)`); }
       if (wantDocx && args.render !== false) { const p = archive + '.docx'; const s = await exportDocx(r.html, p); log.ok(`${path.relative(ctx.project, p)} (${Math.round(s / 1024)} KB)`); }
@@ -128,6 +136,9 @@ export async function build(args) {
   } finally {
     await closeBrowser();
   }
+  // the sections listed by `update` are now in a built document: a later update starts afresh
+  const upd = ctx.p('facts', 'update.json');
+  if (built.length && exists(upd)) { const u = JSON.parse(readText(upd)); if (!u.built) writeJson(upd, { ...u, built: true }); }
   if (args.open && built[0]) { const { open } = await import('./review.js'); await open(built[0].html); }
   return args.strict && failed ? 1 : 0;
 }
@@ -135,7 +146,10 @@ export async function build(args) {
 function report(v, doc) {
   const icon = v.ok ? c.green('✔') : c.red('✖');
   console.log(`${icon} validate ${doc}: score ${v.score}/100 — ${v.errors.length} error(s), ${v.warnings.length} warning(s)`);
-  const show = [...v.errors, ...v.warnings.slice(0, Math.max(0, 25 - v.errors.length))];
+  // what a reader must act on first, then real problems, then the sections still to write (often many)
+  const urgent = (w) => ['comment-reopened', 'open-comments', 'backup', 'comments-missing'].includes(w.code);
+  const pending = v.errors.filter((e) => e.code === 'pending');
+  const show = [...v.warnings.filter(urgent), ...v.errors.filter((e) => e.code !== 'pending'), ...v.warnings.filter((w) => !urgent(w)), ...pending];
   for (const i of show.slice(0, 40)) console.log(`   ${i.level === 'error' ? c.red('error') : c.yellow('warn ')} ${c.dim(i.code)} ${i.message}${i.where ? c.dim('  ' + i.where) : ''}`);
   const hidden = v.errors.length + v.warnings.length - Math.min(40, show.length);
   if (hidden > 0) console.log(c.dim(`   … ${hidden} more (tadforce validate --json)`));
@@ -177,19 +191,26 @@ export async function comments(args) {
 export async function status(args) {
   const ctx = loadWorkspace(args.cwd || process.cwd());
   const f = loadFacts(ctx.ws);
-  const line = (ok, s) => console.log(`${ok ? c.green('✔') : c.dim('○')} ${s}`);
-  log.banner('status');
-  line(!!ctx.cfg.org.alias, `org: ${ctx.cfg.org.alias || 'not set'}`);
-  line(exists(ctx.p('.snapshot', 'package.xml')), 'manifest');
-  line(exists(ctx.p(ctx.cfg.source.dir)), 'snapshot retrieved');
+  const report = { source: ctx.cfg.source.mode || 'org', org: ctx.cfg.org.alias || null, components: f ? f.inventory.length : 0, pending: {} };
+  const line = (ok, s) => { if (!args.json) console.log(`${ok ? c.green('✔') : c.dim('○')} ${s}`); };
+  if (!args.json) log.banner('status');
+  if (ctx.cfg.source.mode === 'local') line(true, 'source: local metadata of the project');
+  else {
+    line(!!ctx.cfg.org.alias, `org: ${ctx.cfg.org.alias || 'not chosen yet (tadforce doctor)'}`);
+    line(exists(ctx.p(ctx.cfg.source.dir)), 'metadata retrieved from the org');
+  }
   line(!!f, `facts${f ? ` (${f.inventory.length} components${f.org ? ', org facts' : ''})` : ''}`);
   for (const doc of DOCS) {
     const dir = ctx.p('src', doc);
     if (!exists(dir)) { line(false, `src/${doc}`); continue; }
-    const text = fs.readdirSync(dir).filter((x) => x.endsWith('.md')).map((x) => readText(path.join(dir, x))).join('\n');
+    // same count as next and validate: sections inside a false <!-- tad:if --> are not part of this document
+    const scope = f ? { modules: f.modules, counts: f.counts, org: f.org, cfg: ctx.cfg, facts: f, glossary: ctx.glossary(), source: sourceFlags(ctx.cfg) } : {};
+    const text = fs.readdirSync(dir).filter((x) => x.endsWith('.md')).map((x) => resolveConditionals(readText(path.join(dir, x)), scope)).join('\n');
     const pending = (text.match(/<!--\s*tad:pending/g) || []).length;
+    report.pending[doc] = pending;
     line(pending === 0, `src/${doc}: ${pending ? pending + ' section(s) to write' : 'written'}`);
   }
+  if (args.json) console.log(JSON.stringify(report, null, 2));
   return 0;
 }