tadforce 0.0.0-stage → 0.2.0

package/skills/tadforce/references/modules/integration-platforms.md

@@ -0,0 +1,19 @@
+# Integration platforms and connected services (MuleSoft, Heroku, Slack, external services, Salesforce Connect)
+
+**Detected by** named credentials and hosts (`*.cloudhub.io`, `*.anypoint.mulesoft.com`, `*.herokuapp.com`, `*.slack.com`), `externalServiceRegistrations`, external objects (`__x`) and `dataSources`, Slack metadata or namespaces.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 9 Integrations | The middleware as a system of its own (named in the glossary: « API Gateway », « MuleSoft »), the APIs consumed through it, External Services (OpenAPI-based actions used by flows and agents), Salesforce Connect external objects (data virtualization), Slack integrations (notifications, Slack apps) |
+| 4 General | Position of the middleware in the context view |
+| 10 Security | Credentials (named / external credentials, principals, per-user vs named principal), integration users, mutual TLS certificates (names only) |
+
+## Read
+
+`namedCredentials`, `externalCredentials`, `externalServiceRegistrations`, `dataSources`, external objects, Apex classes with `callout:`, Integration Procedures with HTTP actions.
+
+## Watch out
+
+What happens behind the middleware is out of scope unless documented: say « exposed by the API Gateway » rather than guessing the system behind it.

package/skills/tadforce/references/modules/marketing.md

@@ -0,0 +1,24 @@
+# Marketing (Marketing Cloud Connect, Account Engagement, Marketing Cloud on the core platform)
+
+**Detected by** namespaces `et4ae5` (Marketing Cloud Connect) or `pi` (Account Engagement / Pardot); Marketing Cloud Growth/Advanced on core shows standard marketing objects and Data Cloud.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 5 Functional | Campaign process: audiences, journeys or engagement programs, sends, tracking back to the CRM, lead scoring and grading, hand-over to sales |
+| 6 Data | `Campaign`, `CampaignMember`, consent objects (`Individual`, `ContactPointTypeConsent`, communication subscriptions), tracking objects of the connector |
+| 9 Integrations | Connector configuration (synchronised objects, triggered sends, business units), direction and frequency, connector user |
+| 10 Security | Connector user and permission sets, consent and unsubscribe handling |
+
+## Read
+
+`et4ae5__*` / `pi__*` references, `objects/Campaign`, `objects/CampaignMember`, consent objects, connector permission sets, triggered-send configurations.
+
+## Draw
+
+Sequence CRM → marketing platform → tracking back; flowchart of the lead hand-over.
+
+## Watch out
+
+The internal configuration of Marketing Cloud (journeys, content, data extensions) is out of the org: put it out of scope unless documents are provided. Never reproduce audiences or personal data.

package/skills/tadforce/references/modules/omnistudio.md

@@ -0,0 +1,24 @@
+# OmniStudio
+
+**Detected by** `omniScripts`, `omniIntegrationProcedures`, `omniDataTransforms`, `omniUiCard`, or namespaces `omnistudio` / `vlocity_*`.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 7 Application | Role split: OmniScripts (guided journeys), Integration Procedures (server-side orchestration, caching), Data Mappers (extract, load, transform), FlexCards (display); naming (`Type/SubType/Language`); one table per family (generated appendix lists the active versions) |
+| 5 Functional | The journeys implemented as OmniScripts, step by step for the main ones |
+| 9 Integrations | HTTP actions and Remote Actions (Apex) called by Integration Procedures |
+| 12 Operations | Deployment of OmniStudio assets (separate step, activation of versions), runtime (standard vs managed package) |
+
+## Read
+
+The `type`, `subType`, `language`, `isActive` of each asset; inside the JSON: elements of type `Integration Procedure Action`, `DataRaptor …`, `Remote Action` (Apex class and method), `HTTP Action` (named credential), custom LWC elements (`lwcName`).
+
+## Draw
+
+Flowchart OmniScript → Integration Procedure → Data Mapper / Apex / HTTP for each main journey.
+
+## Watch out
+
+Only active versions are documented; several versions of the same asset are normal. Standard runtime (on-platform) vs managed package runtime changes deployment and naming: say which.

package/skills/tadforce/references/modules/platform-events.md

@@ -0,0 +1,19 @@
+# Platform Events and Change Data Capture
+
+**Detected by** objects ending with `__e`, `platformEventChannels`, `platformEventChannelMembers` (CDC entities), event-triggered flows and triggers.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 6 Data | `data.events`: each event (purpose, fields in one line), CDC entities selected |
+| 7 Application | Publishers (Apex `EventBus.publish`, flows, processes) and subscribers (triggers on `__e`, platform-event-triggered flows, external subscribers via Pub/Sub API or CometD) |
+| 9 Integrations | External subscribers and publishers, replay and retention, ordering assumptions |
+
+## Draw
+
+Sequence publisher → event bus → subscribers (internal and external).
+
+## Watch out
+
+Publish behaviour (`Publish Immediately` vs `Publish After Commit`) matters for consistency: read the event definition. High-volume events have allocations: mention them as facts.

package/skills/tadforce/references/modules/revenue-cpq.md

@@ -0,0 +1,25 @@
+# Quote-to-cash: Salesforce CPQ, Billing, Revenue Cloud
+
+**Detected by** namespaces `SBQQ` (CPQ), `blng` (Billing), `sbaa` (Advanced Approvals); Revenue Cloud by `ProductSellingModel`, `BillingSchedule`, `Invoice`.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 5 Functional | Quote-to-cash: configure (bundles, options, rules), price (price rules, discount schedules, contracted prices), quote and approve, contract, order, amend and renew, invoice and collect |
+| 6 Data | Product and bundle model, price books, quote / quote line, contract, subscription, order, invoice |
+| 7 Application | Price and product rules (records, not metadata: ask), quote calculator plugins (Apex/JS), approval chains, custom triggers on package objects |
+| 9 Integrations | ERP, e-signature, payment and tax |
+| 10 Security | Package licences and permission sets, approval delegations |
+
+## Read
+
+`SBQQ__*` / `blng__*` fields on local objects, custom fields on package objects, Apex implementing `SBQQ.QuoteCalculatorPlugin*`, approval processes, flows on orders and contracts.
+
+## Draw
+
+Flowchart quote → contract → order → invoice; state diagram of the quote status.
+
+## Watch out
+
+Most CPQ configuration lives in records (price rules, product rules, templates): ask for an export or describe it as configuration to confirm. Do not document package internals.

package/skills/tadforce/references/modules/sales-cloud.md

@@ -0,0 +1,26 @@
+# Sales Cloud
+
+**Detected by** customised `Lead`, `Opportunity`, `Quote`, `OpportunityLineItem`, forecasting types, territory models, Sales Engagement cadences.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 5 Functional | Lead lifecycle (sources, qualification, assignment, conversion, recycling); opportunity pipeline (stages, sales processes per record type, products and price books, quotes); forecasting; territories; activities and cadences |
+| 6 Data | `Lead` → `Account`/`Contact`/`Opportunity` conversion mapping (custom field mapping), opportunity record types and sales processes, path guidance |
+| 7 Application | Assignment rules, lead / opportunity triggers and flows, duplicate and matching rules |
+| 8 UI | Path (`pathAssistants`), Kanban, record pages, Sales console, mobile |
+| 10 Security | Opportunity and Lead OWD, territory-based sharing, opportunity teams, account teams |
+| 11 Reporting | Pipeline and forecast dashboards |
+
+## Read
+
+`objects/Lead`, `objects/Opportunity` (stage picklist, `businessProcesses`, `recordTypes`), `assignmentRules`, `duplicateRules`, `matchingRules`, `pathAssistants`, `forecastingTypes`, `territory2Models`, `quickActions`, lead conversion settings (`settings/Lead.settings-meta.xml`).
+
+## Draw
+
+State diagram of lead statuses and opportunity stages; sequence for web-to-lead or API lead creation → assignment.
+
+## Watch out
+
+Converted leads are read-only (validation rules often enforce it); lead conversion field mapping is in settings, not in fields; forecast categories derive from stages.

package/skills/tadforce/references/modules/security-shield.md

@@ -0,0 +1,18 @@
+# Shield and compliance
+
+**Detected by** platform encryption settings, transaction security policies, event monitoring subscriptions, field history retention policies, data masking configuration (sandboxes).
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 10 Security | `security.shield`: encrypted fields and the encryption scheme (probabilistic, deterministic), key management (tenant secrets, BYOK — never the keys), transaction security policies and their actions, event monitoring usage (login forensics, API usage), field audit trail retention |
+| 12 Operations | Who monitors what, retention and export of event logs |
+
+## Read
+
+`settings/PlatformEncryption*`, `transactionSecurityPolicies`, `settings/EventSettings*`, objects with `historyRetentionPolicy`, encrypted field metadata (`encryptionScheme`).
+
+## Watch out
+
+Never reproduce keys, secrets or certificates. Encryption affects search, formulas and filters: state the constraints observed, put the risks in the Improvement Axes.

package/skills/tadforce/references/modules/service-cloud.md

@@ -0,0 +1,27 @@
+# Service Cloud
+
+**Detected by** customised `Case`, entitlements and milestones, Omni-Channel (service channels, routing configurations, presence), messaging and chat sessions, voice calls, knowledge articles (`*__kav`).
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 5 Functional | Case lifecycle: channels in (e-mail-to-case, web-to-case, messaging, voice, portal, API), triage, assignment and escalation, SLA (entitlements, milestones), resolution, closure, surveys; knowledge usage |
+| 6 Data | `Case` record types and support processes, `Entitlement`, `ServiceContract`, `CaseMilestone`, knowledge article types and data categories |
+| 7 Application | Assignment, auto-response and escalation rules; case triggers and flows; macros and quick text |
+| 8 UI | Service console, utility bar (softphone, omni widget, history), case record pages; telephony (Service Cloud Voice or CTI adapter via `callCenters`) and Omni-Channel (channels, queues, skills, capacity, presence statuses) |
+| 9 Integrations | Telephony provider, messaging providers (WhatsApp, SMS), e-mail routing addresses |
+| 10 Security | Case sharing, queue membership, support profiles and permission set groups, Experience Cloud case access |
+| 11 Reporting | Service KPIs (backlog, first contact resolution, SLA attainment) |
+
+## Read
+
+`objects/Case`, `entitlementProcesses`, `milestoneTypes`, `assignmentRules/Case`, `autoResponseRules`, `escalationRules`, `serviceChannels`, `queueRoutingConfigs`, `presenceUserConfigs`, `servicePresenceStatuses`, `callCenters`, `queues`, `settings/Case.settings-meta.xml`, `settings/EmailToCase*`, `quickActions`, messaging channels.
+
+## Draw
+
+Flowchart of case channels → routing → queues → agents; state diagram of case statuses; sequence of an inbound call or message with Omni-Channel.
+
+## Watch out
+
+Routing may be queue-based or skills-based (attribute routing): say which. Omni-Channel capacity and presence are configuration, not code. Do not reproduce e-mail addresses or phone numbers.

package/skills/tadforce/references/naming-external-systems.md

@@ -0,0 +1,32 @@
+# Naming external systems and imposing the client's terms
+
+A wrong system name in a client document is the fastest way to lose the reader's trust. It happens when a name is inferred from a field (`LegacyCoreId__c`), a class (`CoreBankingClient`) or a host (`api-int-07.example`). TADForce forbids it.
+
+## Where systems come from
+
+`tadforce facts` groups the endpoints seen from Salesforce — named credentials, external credentials, remote sites, CSP trusted sites, auth providers, connected apps, call centers — and matches them with `knowledge/glossary.yml › systems`. Unmatched endpoints land in `facts/questions.json › systems`.
+
+```yaml
+systems:
+  - id: core
+    name: "Core banking"                         # exactly as the client says it
+    description: "System of record for accounts and contracts"
+    match: ["Core_API", "api.core.example.com"]   # component names or hosts (sub-domains match)
+actors:
+  - name: "Branch advisors"
+    channel: "Branch console"
+terms:
+  - use: "API Gateway"
+    avoid: ["API passerelle", "middleware"]
+    definition: "Single entry point exposing the internal services."   # goes to the glossary appendix
+allow: [customerId, offerCode]   # identifiers quoted on purpose that are not metadata (API payload fields…)
+```
+
+## Rules
+
+1. Ask, with the evidence: host, named credential, the classes or Integration Procedures that call it.
+2. Propose a name only when the host is unambiguous about a vendor (`*.twilio.com` → Twilio).
+3. Data teams, middleware and gateways are systems too: name them as the client does (« DATA », « API Gateway »).
+4. Inbound callers (connected apps, Apex REST) are systems as well: who calls `/leads/v1/*`?
+5. Once named, use the name everywhere — text, tables, sequence participants, flowchart nodes.
+6. Terms with `avoid` are checked by `tadforce validate` (whole words, case-insensitive).

package/skills/tadforce/references/questions.md

@@ -0,0 +1,59 @@
+# Questions — what only a human can answer
+
+Ask in **blocks**, each in one message, with your proposed answer for every item so the human only confirms or corrects. Write the question in the human's language.
+
+## 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:
+
+1. Document language — recommended: the org default language.
+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).
+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).
+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]`.
+
+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.
+
+## Block B — external systems (from `facts/questions.json › systems`)
+
+One line per endpoint group: « `api.example.com` (named credential `X_API`, used by `ClassA`, `ClassB`) — which system is it, and how does the client call it? »
+
+Rules: never propose a product name you inferred from a field or class name; you may propose the host's organisation when it is explicit (`*.salesforce.com`, `*.twilio.com`, `*.docusign.net`).
+
+Write:
+
+```yaml
+systems:
+  - id: core
+    name: "Core banking"
+    description: "System of record for accounts and contracts"
+    match: ["X_API", "api.example.com"]
+```
+
+## Block C — candidates for exclusion (from `facts/questions.json › exclusions.groups`)
+
+Present each group with its count and up to 10 names; ask for a decision per group, with exceptions:
+
+> 14 components look unused (not placed on any page, app, tab or action): `lwcA`, `lwcB`, … Exclude them from the document? (yes / no / all except …)
+
+Write only the confirmed ones in `exclusions.yml › exclude` with the reason given by the human.
+
+## Block D — knowledge only people have
+
+1. Features that were **decommissioned** but whose components are still deployed? (names, components, keywords to ban)
+2. Terms the client imposes (« API Gateway » rather than « middleware »…)?
+3. Documents to use as inputs (specifications, previous architecture document, release procedure)? → `knowledge/inputs/`
+4. Environments (sandboxes and their purpose) and the release process, if not visible in the project.
+5. User populations (names the client uses) → `glossary.yml › actors`.
+
+## During writing
+
+Ask only when a section cannot be written without it, and batch these questions every few sections. Otherwise write the fact you have and mark the rest « to be confirmed » (FR « à confirmer »).

package/skills/tadforce/references/salesforce-skills.md

@@ -0,0 +1,27 @@
+# Salesforce skills worth calling
+
+Salesforce publishes official agent skills (`forcedotcom/sf-skills`). Install only those you need, for the agents you use:
+
+```bash
+npx skills add forcedotcom/sf-skills --skill platform-architecture-analyze --skill dx-code-analyzer-run --skill platform-metadata-retrieve --skill platform-soql-query --skill platform-docs-get --skill external-diagram-mermaid-generate
+```
+
+Never install all of them for every agent: dozens of folders, hundreds of copies, slower agents.
+
+| Skill | Use in TADForce | When |
+|---|---|---|
+| `platform-architecture-analyze` | Well-Architected reading of code and metadata | Chapter 13 and the Improvement Axes |
+| `dx-code-analyzer-run` | Code Analyzer (PMD, ESLint, Flow, ApexGuru…) | Save JSON as `knowledge/inputs/code-analyzer-results.json` |
+| `dx-org-analyze` | Org inventory: licenses, limits, packages | Cross-check `facts/org.json` |
+| `platform-metadata-retrieve` | Retrieve help, partial retrieves | When a type failed in `tadforce retrieve` |
+| `platform-manifest-generate` | Manifest edge cases | Custom manifests |
+| `platform-soql-query` | Aggregated queries (never record data in the document) | Volumes or usage not in org facts |
+| `platform-docs-get` | Official Salesforce documentation | References chapter, product behaviour |
+| `platform-data-and-tooling-api-context-get` | Standard object and field reference | Understanding standard / industry objects |
+| `external-diagram-mermaid-generate` | Mermaid diagrams for Salesforce | Complex sequences |
+| `omnistudio-dependencies-analyze` | OmniScript / IP / Data Mapper dependencies | OmniStudio detected |
+| `agentforce-architecture-analyze` | Agent topics, actions, prompts | Agentforce detected |
+| `data360-schema-get` | Data Cloud schema | Data Cloud detected |
+| `crm-analytics-wave-generate` (read-only use) | CRM Analytics assets | CRM Analytics detected |
+
+Rules: use them **read-only**. Skills that deploy, generate metadata or change the org are out of scope for documentation.

package/skills/tadforce/references/workflow.md

@@ -0,0 +1,85 @@
+# Workflow — from an empty folder to a validated document
+
+Four commands: **doctor → build → review → update**. Run them from the root of the Salesforce DX project (the folder that holds, or will hold, `sfdx-project.json`). As an agent, always use `--json` and decide from the output.
+
+## 1. `doctor` — everything before the writing
+
+```bash
+npx tadforce doctor --json
+```
+
+`doctor` is a loop: run it, act on its answer, run it again until `ok: true`. Each answer holds `checks[]` (each with `level`, `fix`, `human`), `questions[]` (each with a `recommended` answer) and `next`.
+
+| `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` |
+| `tadforce build` | Ready: write and build |
+
+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/`;
+- 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`.
+
+### Optional inputs
+
+- **Functional specifications** (`--specs`): copied into `knowledge/inputs/specs/`. Read them before chapters 3 and 5; they are evidence level P2/P3 (`evidence-rules.md`). They explain the *why*; the metadata still decides the *what*.
+- **Scope** (`--scope`): name patterns of the components the project owns. Out-of-scope components disappear from facts, counts and tables; standard objects and org-wide components (profiles, roles, queues, reports) stay. Package directories: `--package-dirs force-app,core`.
+- **Quality inputs** (recommended): `platform-architecture-analyze` (Salesforce skill) for chapter 13 and the Improvement Axes; `dx-code-analyzer-run` → `tadforce/knowledge/inputs/code-analyzer-results.json`. See `salesforce-skills.md`.
+
+## 2. `build` — write, then build
+
+Write first:
+
+```bash
+npx tadforce next --json
+```
+
+Loop until `remaining` is 0. For each section: spec → facts → code → content. Write the TAD first (chapters 1 to 15), then the Improvement Axes (`--doc axes`). Do not edit the generated tables: change the facts or the knowledge files instead.
+
+Efficient order: 6 Data → 7 Application → 8 UI → 9 Integrations → 10 Security → 11-13 → 5 Functional → 4 General → 1-3 (the summary is written last, from what you learned). Run `npx tadforce validate` every few sections.
+
+Then build:
+
+```bash
+npx tadforce build --pdf --docx      # HTML always; PDF and Word on demand
+```
+
+Fix every error reported by the validation (pending sections, unknown placeholders, excluded components, forbidden terms, broken anchors, Mermaid errors, possible secrets). Review warnings: an unknown identifier is either a typo, a package component (fine, say so) or a hallucination (remove it).
+
+The HTML keeps **one name across versions** (`out/TAD_<CODE>.html`): comments saved in it are carried into every rebuild. PDF and DOCX carry the version (`TAD_<CODE>_v1.0.pdf`) — they are archives.
+
+Hand over, briefly: where the files are, the score, what is *to be confirmed*, and how to review.
+
+## 3. `review` — comments become fixes
+
+The human runs `npx tadforce review`: the document opens from a local server and **Save writes into the same file** — no copies, no lost comments. (Opened by double-click, the page asks to pick the file: pick that same file.)
+
+Then `/tadforce-review` (skill `tadforce-review`): `npx tadforce review --json` lists the open comments; each one becomes a fix in the sources and, when it is a rule, in the knowledge files.
+
+## 4. `update` — months later
+
+```bash
+npx tadforce update --json
+```
+
+Archives the previous facts in `facts/history/<date>/`, reads the org again (fresh snapshot), compares content fingerprints, bumps the version (`1.0 → 1.1`) with a line in the history, and returns the sections to review with the reasons (`changes`, `counts`, `sections[]` with file and anchor). Rewrite only those sections (skill `tadforce-update`), then `npx tadforce build`. Counts, tables, ERDs and appendices update by themselves.
+
+## Advanced commands (CI, experts)
+
+`npx tadforce help --all`: `init`, `auth`, `detect`, `manifest [--mode full]`, `retrieve [--batch-size 5]`, `facts [--source <dir>]`, `prepare`, `scaffold`, `next`, `spec`, `validate`, `comments`, `status`, `install-skills`.
+
+## Failure handling
+
+| Symptom | Action |
+|---|---|
+| `sf` asks to log in again | The human runs `npx tadforce doctor` (it opens the browser) |
+| Retrieve batch fails | It retries type by type; read `.snapshot/retrieve-report.json`; rerun later or `npx tadforce retrieve --batch-size 5` |
+| Mermaid error in a figure | Simplify the diagram (labels in quotes, no parentheses in node ids), rebuild |
+| `unknown-component` warnings on package objects | Normal when the object belongs to a package: write it with its namespace |
+| The human says a fact is wrong | Correct the knowledge file (exclusion, glossary) rather than the text, rerun facts, rebuild |
+| Colours or logo wrong | Edit `tadforce.config.json › brand` / `client.logo`, or `doctor --json --logo <file>` |

package/skills/tadforce/references/writing-rules.md

@@ -0,0 +1,47 @@
+# Writing rules — a document the client keeps
+
+The reader is an architect, an application owner, an operations or security engineer of the client, or a developer joining the project. They read it on screen, print it, and come back to it months later.
+
+## Voice
+
+- Present tense, as implemented: « The platform assigns… », not « will assign » or « should ».
+- Factual and positive. Describe what exists and why it was designed this way. No blame, no defect list, no « unfortunately ».
+- Precise and short: one idea per sentence; paragraphs of 2 to 5 sentences.
+- The integrator's design choices are highlighted in `> [!INTEGRATOR]` callouts, sparingly (one per chapter at most).
+- No marketing words (« revolutionary », « seamless », « best-in-class »).
+
+## Structure
+
+- Keep the skeleton: chapters, sections and anchors are the same for every org; that is what makes TADForce documents comparable.
+- Start each section with the sentence a reader needs if they read nothing else.
+- Prefer a table when you compare three or more items on the same attributes.
+- Lists: parallel grammar, no full stop for fragments, full stop for sentences.
+- Cross-reference with `{{ref:id}}` instead of repeating content (« see {{ref:annex-automation}} »).
+- Full inventories belong in the appendices (generated). Chapters keep the 5 to 10 items that matter.
+
+## Names
+
+- Technical names in code font: `LoanApplication__c`, `LeadTriggerHandler`, `customer360`. They must exist in the inventory.
+- Business labels in quotes: « Loan application » (FR: « Demande de prêt »).
+- Salesforce terms in English in every language: Lead, Opportunity, Case, Queue, Record Type, Permission Set Group, Named Credential, Flow, OmniScript, Integration Procedure.
+- External systems with the name from `glossary.yml`, nothing else.
+- Apply `glossary.yml › terms` (`use` / `avoid`) everywhere, including figures.
+
+## Numbers
+
+- Every count comes from a placeholder: `{{n:apex.classes}}`, `{{n:flows.active}}`, `{{n:security.permissionSetGroups}}`. The list of keys is in `facts.json › counts`.
+- Thresholds read in code (batch size, number of retries) are written as numbers with the class that defines them.
+- Never write a volume, a number of users or a performance figure that is not in the facts or the inputs.
+
+## Language
+
+- Write in the document language. French: typographic conventions (espace insécable avant « : ; ! ? », guillemets « »), « vous » never used — impersonal style.
+- Do not translate API names, picklist values or labels shown in the UI; quote them.
+
+## Length (indicative, a medium org)
+
+Summary 1 page · chapters 2 to 4: 1 to 2 pages each · chapter 5: 1 page per domain · chapters 6 to 10: 2 to 5 pages each · chapters 11 to 15: half a page to 2 pages. Appendices: generated.
+
+## What never goes into the TAD
+
+Debt, risks, code smells, scores, recommendations, team or vendor names other than the client and the integrator, personal data, credentials, record IDs, org IDs, URLs with tokens, decommissioned features, excluded components.

package/skills/tadforce-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: tadforce-review
+description: Process the review comments that readers left in a TADForce HTML document (Comment / Capture an area, then Save) — apply each correction to the sources and to the knowledge files so it survives regenerations, mark it resolved with an answer, rebuild. Use when the user says the document was reviewed or commented, shares a saved HTML file with comments, or runs /tadforce-review.
+---
+
+# TADForce review loop
+
+Readers comment directly in the HTML (💬 Comment, ＋ Capture an area, 💾 Save). Comments are stored inside the file, with the quoted passage, the section and an optional screenshot. Your job: turn every comment into a lasting correction, and answer it.
+
+The document has **one file across versions**: `tadforce/out/TAD_<CODE>.html`. The human opens it with `npx tadforce review`: Save in the page writes into that same file, so no comment is lost in a copy.
+
+## 1. Collect
+
+```bash
+npx tadforce review --json                  # open comments of tadforce/out/TAD_<CODE>.html
+npx tadforce review <path/to/other.html> --json
+```
+
+If the human sent a copy from elsewhere (e-mail, downloads folder), use that path and add it to `commentsFrom` (step 3). Images are attached in the file: open the HTML in a browser if you need to see a capture.
+
+## 2. Classify each open comment
+
+| Kind | Example | Where the fix goes |
+|---|---|---|
+| Terminology | « Say API Gateway, not passerelle, everywhere » | `knowledge/glossary.yml › terms` (`use` / `avoid`) **and** the text |
+| System name | « This is not the legacy core banking, it is the Data Platform » | `glossary.yml › systems` (name, match) **and** the text and figures |
+| Decommissioned | « This search was decommissioned, do not mention it » | `knowledge/exclusions.yml › features` (components, keywords) **and** remove from the text |
+| Out of scope component | « This LWC is a POC » | `exclusions.yml › exclude` |
+| Factual correction | « The batch runs every hour, not daily » | The text; check the metadata first and say if it contradicts the comment |
+| Process change | « The flow is simpler now: … » | Rewrite the section from the new description; move open questions to the Improvement Axes |
+| Layout / readability | « Table headers are not readable » | Report it to the human (template issue) or adjust the content (split a table) |
+
+When the comment contradicts the metadata, do not silently obey: answer with the evidence and ask.
+
+## 3. Apply
+
+1. Edit `tadforce/src/<doc>/*.md` (never the built HTML).
+2. Edit the knowledge files; then `npx tadforce facts` if exclusions or systems changed.
+3. In `tadforce/tadforce.config.json`, under `review.<doc>`:
+   - comments of `out/TAD_<CODE>.html` itself are carried over automatically; only a copy saved elsewhere goes to `commentsFrom` (path relative to `tadforce/`);
+   - add one entry per handled comment to `resolutions`: `"<comment id>": "<what you changed, one or two sentences, with section numbers>"`;
+   - 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.
+
+## 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.
+
+## Rules
+
+- A correction lands in the knowledge files whenever it is a rule (term, system, exclusion), so the next regeneration keeps it.
+- Never delete a comment; resolve it with an answer.
+- Apply a terminology fix everywhere (text, tables, figure labels, sequence participants), then run `npx tadforce validate` — forbidden terms are checked automatically.

package/skills/tadforce-update/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: tadforce-update
+description: Bring an existing TADForce Technical Architecture Document up to date after the org evolved (new or changed Apex, flows, objects, integrations, permissions, products) — reads the org again, compares with the facts the previous version was written from, rewrites only the impacted sections, bumps the version. Use when the user says the document is outdated, asks to refresh or update the TAD, mentions a new release or several months of changes, or runs /tadforce-update.
+---
+
+# TADForce update — the document follows the org
+
+The document already exists. Do not rewrite it: find what changed, and rewrite only what it touches. The rules of the `tadforce` skill still apply (no evidence, no sentence; numbers from facts; the client's vocabulary is law).
+
+## 1. Compare
+
+```bash
+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:
+
+- `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.
+
+Nothing changed: say so and stop.
+
+## 2. Ask, once
+
+New external endpoints and new unused-looking components appear in `facts/questions.json`. Ask about them in one message (Blocks B and C of the `tadforce` skill's `references/questions.md`), write the knowledge files, rerun `npx tadforce facts`.
+
+## 3. Rewrite only what changed
+
+For each section of `sections[]`:
+
+1. Open `file` at `anchor`, read the current text.
+2. Read the spec (`npx tadforce spec <id> --json`) and the changed metadata (`tadforce/.snapshot/source/...`). For a changed Apex class or flow, read the code: what the reader must learn is the new *behaviour*, not that a file changed.
+3. Edit the section: add the new components, update the behaviour that changed, remove what was deleted. Keep the heading and its anchor; keep everything that is still true word for word — readers have already validated it.
+4. Placeholders (`{{n:…}}`), generated tables, ERDs and appendices update by themselves: never edit them by hand.
+
+A section listed only for moved counts usually needs no change: check that the text holds no number or statement that the new counts contradict.
+
+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).
+
+## 4. Build and report
+
+```bash
+npx tadforce build --pdf --docx
+```
+
+0 errors. The HTML keeps its name: the comments readers left on the previous version are still in it. Report in a few lines: version `from → to`, the sections rewritten (with one line each on what changed), the questions still open. Ask the human to review the new version with `npx tadforce review`.