tadforce 0.0.0-stage → 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "tadforce",
+  "owner": {
+    "name": "Jihad AZAMI HASSANI"
+  },
+  "metadata": {
+    "description": "TADForce — technical architecture documents for Salesforce orgs, written by your agent from the org's own metadata."
+  },
+  "plugins": [
+    {
+      "name": "tadforce",
+      "source": "./",
+      "description": "Generate, review and validate the Technical Architecture Document of any Salesforce org (/tadforce, /tadforce-review).",
+      "version": "0.2.0",
+      "author": { "name": "Jihad AZAMI HASSANI" },
+      "license": "Apache-2.0",
+      "category": "documentation"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "tadforce",
+  "version": "0.2.0",
+  "description": "Point it at a Salesforce org, get the Technical Architecture Document a senior architect would write: evidence-based, reproducible, reviewable in the browser. All Salesforce products and industries.",
+  "author": {
+    "name": "Jihad AZAMI HASSANI",
+    "url": "https://github.com/azamiji"
+  },
+  "homepage": "https://github.com/azamiji/TADForce",
+  "repository": "https://github.com/azamiji/TADForce",
+  "license": "Apache-2.0",
+  "keywords": ["salesforce", "architecture", "documentation", "technical-architecture-document", "sfdx", "well-architected"]
+}

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+TADForce
+Copyright 2026 Jihad AZAMI HASSANI
+
+This product includes software developed by third parties, shipped unmodified in templates/vendor/:
+- Mermaid 11.4.1 (MIT License) — https://mermaid.js.org
+- html2canvas 1.4.1 (MIT License) — https://html2canvas.hertzen.com
+- html-docx-js 0.3.1 (MIT License) — https://github.com/evidenceprime/html-docx-js
+Their license texts are in templates/vendor/LICENSE-*.txt.
+
+Salesforce and related product names are trademarks of Salesforce, Inc. TADForce is an independent
+community project, not affiliated with, sponsored or endorsed by Salesforce.

package/README.fr.md

@@ -0,0 +1,125 @@
+<div align="center">
+
+<img src="assets/banner.svg" alt="TADForce" width="100%">
+
+### Le scribe de l'architecte pour les orgs Salesforce.
+
+**Quatre commandes. Une org. Un document d'architecture technique fondé sur des preuves, reproductible, relu dans le navigateur.**
+
+[English](README.md) · [**Démo en ligne**](https://azamiji.github.io/TADForce/)
+
+</div>
+
+<img src="assets/divider.svg" width="100%" alt="">
+
+## Pourquoi TADForce
+
+Rédiger le document d'architecture technique d'une org Salesforce prend des semaines, et il est périmé à la release suivante. Un chat IA générique l'écrit en une heure, puis on passe des jours à vérifier ce qu'il a inventé.
+
+TADForce lit l'org comme le ferait un architecte Salesforce senior — chaque classe, Flow, objet, Permission Set Group, Named Credential et OmniScript — et votre agent IA rédige le document à partir de ces preuves. Une seule règle : **pas de preuve, pas de phrase.** Si les métadonnées ne le prouvent pas, l'agent vous pose la question ou écrit « à confirmer ». Il ne devine jamais le nom d'un système, ne documente jamais une fonction décommissionnée et ne tape jamais un chiffre à la main.
+
+<div align="center">
+<img src="assets/gifs/document.gif" alt="Navigation dans un document généré par TADForce" width="92%">
+</div>
+
+## ⚡ Démarrage
+
+**Prérequis** : Node.js 20+, Salesforce CLI (`sf`), Chrome ou Edge, un agent IA. `doctor` vérifie tout et installe ce qu'il peut.
+
+À la racine de votre projet Salesforce DX (ou dans un dossier vide) :
+
+```bash
+npx tadforce doctor
+```
+
+Puis, dans votre agent IA (Claude Code, Codex, Cursor, Copilot…) :
+
+```text
+/tadforce
+```
+
+| Chemin | Commandes |
+|---|---|
+| Plugin Claude Code | `/plugin marketplace add azamiji/TADForce` puis `/plugin install tadforce@tadforce` |
+| Tout agent (Agent Skills) | `npx tadforce doctor` installe les skills dans `.claude/`, `.agents/`, `.cursor/`, `.codex/`… |
+| Déterministe / CI | `npx tadforce prepare --org prod`, puis `npx tadforce build --pdf --docx`, puis `npx tadforce validate` |
+
+## 🧭 Quatre commandes
+
+| Commande | Ce qu'elle fait | Votre part |
+|---|---|---|
+| `npx tadforce doctor` | Tout ce qui précède la rédaction, en boucle jusqu'à ce que tout soit vert : outils, projet SFDX, connexion à l'org (réutilise la `target-org` du projet, n'ouvre le navigateur que si nécessaire), métadonnées (récupérées depuis l'org avec un manifest `*`, ou vos sources locales), logo et couleurs du client, puis les questions dont seul un humain connaît la réponse | Vous connecter une fois ; valider les réponses recommandées ; nommer les systèmes externes ; confirmer ce qui est inutilisé ou décommissionné |
+| `npx tadforce build` | Votre agent rédige chaque section à partir de sa fiche et des faits, puis le document est produit : **HTML** toujours, **PDF** et **Word** à la demande, et validé | — |
+| `npx tadforce review` | Ouvre le document pour le commenter. **Enregistrer écrit dans le même fichier** : un seul fichier par document, pas de copies, aucun commentaire perdu. Puis `/tadforce-review` transforme chaque commentaire en correction | Commenter un passage ou capturer une zone, Enregistrer |
+| `npx tadforce update` | Quelques mois plus tard : relit l'org, archive les faits précédents, liste les sections touchées par ce qui a changé (une classe Apex ajoutée, un Flow modifié, de nouveaux chiffres…), incrémente la version. `/tadforce-update` ne réécrit que ces sections | — |
+
+<div align="center">
+<img src="assets/gifs/doctor.gif" alt="tadforce doctor pose les questions dont seul un humain connaît la réponse" width="80%">
+</div>
+
+Les commandes fines (`manifest`, `retrieve`, `facts`, `next`, `validate`…) restent disponibles pour la CI et les experts : `npx tadforce help --all`.
+
+## 📦 Ce que vous obtenez
+
+- **Document d'architecture technique**, destiné au client :
+  - en HTML : navigable, modifiable en place, avec commentaire d'un passage ou capture d'une zone, enregistrement dans le même fichier et export PDF ou Word ;
+  - en PDF A4 et en DOCX, la version dans le nom du fichier.
+- **Axes d'amélioration**, document interne à l'intégrateur : signaux mesurés par pilier Well-Architected, registre `AX-nn` et feuille de route. Ils restent hors du document client.
+- **`facts.json`** : l'inventaire déterministe de l'org, identique octet pour octet d'une exécution à l'autre.
+
+Le document porte **le logo et les couleurs du client** : le logo est cherché dans l'org (static resources, content assets, assets des sites) ou fourni par vous ; les couleurs viennent du thème Lightning de l'org, sinon du logo, toujours lisibles (contraste WCAG vérifié). L'intégrateur et l'auteur sont facultatifs : laissés vides, le document ne nomme que le client.
+
+<div align="center">
+<img src="assets/gifs/review.gif" alt="Commenter un passage dans le HTML et l'enregistrer dans le même fichier" width="92%">
+</div>
+
+## 🧩 Tous les types de projets Salesforce
+
+| Votre situation | Comment TADForce s'y adapte |
+|---|---|
+| **Une org complète**, état existant | `doctor` récupère tout avec un manifest `*` maîtrisé (130 types, rapports et tableaux de bord dans leurs dossiers, objets standard) |
+| **Un projet dans une org partagée** (plusieurs BU, plusieurs intégrateurs) | Périmètre : `--scope "NWB_*,Loan*"` ou `--package-dirs`. Les composants hors périmètre sortent des faits, des chiffres et des tableaux ; les objets standard et les réglages globaux restent |
+| **Avant ou pendant le build** | Fournissez vos spécifications fonctionnelles (`--specs SFD.pdf,…`) : elles deviennent des preuves (niveau P2/P3) à côté des métadonnées |
+| **Sans accès à l'org**, sources seules | `--source local` documente les package directories du projet |
+| **Packages unlocked ou managés** | Namespaces et packages installés sont détectés et documentés avec leurs preuves |
+| **Tous les clouds, toutes les industries** | Une section ne s'active que si le produit est détecté, avec sa fiche de rédaction |
+
+- **Clouds** : Sales, Service, Field Service, Experience, Marketing, Commerce, CPQ et Revenue ;
+- **Industries** : Financial Services, Insurance, Health, Life Sciences, Manufacturing, Automotive, Consumer Goods, Communications, Public Sector, Education, Nonprofit, Loyalty, Net Zero ;
+- **Plateforme** : OmniStudio, Data Cloud, Agentforce, CRM Analytics, Platform Events, Shield, MuleSoft, Heroku et Slack.
+
+## 🔒 Lecture seule par construction
+
+- **Liste blanche des commandes `sf`** : pas de deploy, pas de suppression, pas d'exécution d'Apex.
+- **Garde-fou SOQL** : seuls les objets de configuration de l'org et les agrégats sont lus, jamais les données métier.
+- **`force-app` jamais modifié** : la récupération se fait dans `tadforce/.snapshot`.
+- **Aucun secret dans le texte** : la validation bloque les secrets et les identifiants d'org.
+
+**Ce qui sort de votre poste** : le CLI TADForce n'envoie rien nulle part — ni télémétrie, ni serveur, ni compte. Il parle à votre org via votre propre Salesforce CLI, et au web seulement quand **vous** lui donnez l'URL d'un logo. Votre agent IA lit les métadonnées, les faits et les spécifications que vous fournissez pour rédiger, exactement comme lorsque vous lui faites lire votre code. Utilisez l'agent et les réglages de confidentialité validés par votre entreprise pour les travaux client.
+
+## 🎯 Reproductible
+
+- **Les chiffres sont des placeholders**, par exemple `{{n:apex.classes}}`.
+- **Les tableaux, les ERD, la hiérarchie des rôles et les annexes sont générés.**
+- **84 fiches de section** cadrent la rédaction de n'importe quel agent.
+- **`npx tadforce validate`** bloque tout ce qui ne doit pas être livré.
+
+## 👤 Auteur
+
+<table>
+<tr>
+<td width="110"><img src="https://github.com/azamiji.png" width="96" alt="Jihad AZAMI HASSANI"></td>
+<td>
+
+**Jihad AZAMI HASSANI**<br>
+Salesforce Technical Architect, 10+ ans d'expérience · Claude Certified Architect · Leader du Salesforce Architect Community Group de Casablanca<br>
+[![Claude Certified Architect](https://img.shields.io/badge/Claude-Certified%20Architect-D97757?logo=claude&logoColor=white)](https://www.linkedin.com/in/jihadazami/)<br>
+[LinkedIn](https://www.linkedin.com/in/jihadazami/) · [GitHub](https://github.com/azamiji)
+
+</td>
+</tr>
+</table>
+
+## ⚖️ Licence
+
+[Apache-2.0](LICENSE). Salesforce et les noms de ses produits sont des marques de Salesforce, Inc. TADForce est un projet communautaire indépendant, ni affilié à Salesforce ni approuvé par elle. L'organisation de l'exemple (Northwind Bank, Acme Integrators) est fictive.

package/README.md

@@ -1,3 +1,257 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/banner.svg" alt="TADForce — point it at a Salesforce org, get the architecture document a senior architect would write" width="100%">
+
+### The architect's scribe for Salesforce orgs.
+
+**Four commands. One org. One Technical Architecture Document — evidence-based, reproducible, reviewable in the browser.**
+
+[![npm](https://img.shields.io/npm/v/tadforce?color=7B3FE4&label=npm&logo=npm)](https://www.npmjs.com/package/tadforce)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-1E88FF)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/azamiji/TADForce?style=flat&color=FFD54F&logo=github)](https://github.com/azamiji/TADForce/stargazers)
+[![CI](https://img.shields.io/github/actions/workflow/status/azamiji/TADForce/ci.yml?label=tests&logo=githubactions&logoColor=white)](https://github.com/azamiji/TADForce/actions)
+![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=nodedotjs&logoColor=white)
+![Salesforce CLI](https://img.shields.io/badge/sf%20CLI-v2-00A1E0)
+
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-open%20standard-0B2545)](https://agentskills.io)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-D97757)](#-quick-start)
+[![Codex](https://img.shields.io/badge/Codex-skill-111111)](#-quick-start)
+[![Cursor](https://img.shields.io/badge/Cursor-skill-3B82F6)](#-quick-start)
+[![Copilot](https://img.shields.io/badge/GitHub%20Copilot-skill-6E40C9)](#-quick-start)
+[![Read-only](https://img.shields.io/badge/org%20access-read--only-16A34A)](#-read-only-by-design)
+
+[**Live demo**](https://azamiji.github.io/TADForce/) · [Quick start](#-quick-start) · [The four commands](#-four-commands) · [Every project type](#-every-kind-of-salesforce-project) · [Français](README.fr.md)
+
+</div>
+
+<img src="assets/divider.svg" width="100%" alt="">
+
+## Why TADForce
+
+Writing the Technical Architecture Document of a Salesforce org takes weeks, and it is out of date at the next release. A generic AI chat writes it in an hour, then you spend days checking what it made up.
+
+TADForce reads the org the way a senior Salesforce architect would — every class, flow, object, permission set group, named credential and OmniScript — and your AI agent writes the document from that evidence. One rule: **no evidence, no sentence.** If the metadata does not prove it, the agent asks you or writes *to be confirmed*. It never guesses the name of a system, never documents a feature you switched off, and never types a number by hand.
+
+<div align="center">
+<img src="assets/gifs/document.gif" alt="Navigating a Technical Architecture Document generated by TADForce" width="92%">
+<br><sub>The generated document: navigable contents, KPI tiles that link to their appendix, figures drawn from the metadata.</sub>
+</div>
+
+## 🚀 Quick start
+
+**Prerequisites:** Node.js 20+, the [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli) (`sf`), Chrome or Edge, and an AI agent. `doctor` checks all of it and installs what it can.
+
+From your Salesforce DX project (or an empty folder):
+
+```bash
+npx tadforce doctor
+```
+
+Then, in your AI agent (Claude Code, Codex, Cursor, Copilot…):
+
+```text
+/tadforce
+```
+
+<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>
+<tr valign="top"><td>
+
+```text
+/plugin marketplace add azamiji/TADForce
+/plugin install tadforce@tadforce
+/tadforce
+```
+
+</td><td>
+
+```bash
+npx tadforce doctor
+# skills land in .claude/, .agents/,
+# .cursor/, .codex/… (detected)
+```
+then ask your agent: *“run /tadforce”*
+
+</td><td>
+
+```bash
+npx tadforce prepare --org prod
+npx tadforce build --pdf --docx
+npx tadforce validate --json
+```
+
+</td></tr>
+</table>
+
+## 🧭 Four commands
+
+| Command | What it does | Your part |
+|---|---|---|
+| `npx tadforce doctor` | Everything before the writing, in one loop until all is green: tools, SFDX project, org connection (reuses the project's `target-org`, opens the browser only when needed), metadata (retrieved from the org with a `*` manifest, or your local sources), client logo and colours, then the questions only a human can answer | Log in once; confirm the answers it recommends; name the external systems; confirm what is unused or decommissioned |
+| `npx tadforce build` | Your agent writes each section from its specification and the facts, then the document is built: **HTML** always, **PDF** and **Word** on demand, and validated | — |
+| `npx tadforce review` | Opens the document to comment it. **Save writes into the same file** — one file per document, no copies, no lost comments. Then `/tadforce-review` turns every comment into a fix | Comment a passage or capture an area, Save |
+| `npx tadforce update` | Months later: reads the org again, archives the previous facts, lists the sections touched by what changed (a new Apex class, a modified flow, new counts…), bumps the version. `/tadforce-update` rewrites only those sections | — |
+
+<div align="center">
+<img src="assets/gifs/doctor.gif" alt="tadforce doctor asking the few questions only a human can answer" width="80%">
+<br><sub><code>doctor</code>: one loop, a recommended answer for every question.</sub>
+</div>
+
+```mermaid
+flowchart LR
+  A["doctor<br>tools · org · metadata · questions"]:::h --> B["write<br>15 chapters"]:::a
+  B --> C["build<br>HTML · PDF · DOCX"]:::s
+  C --> D["review<br>comments in the HTML"]:::h
+  D --> B
+  C -. months later .-> E["update<br>what changed"]:::s
+  E --> B
+  classDef s fill:#E8F1FF,stroke:#2F6FE4,color:#0B2545
+  classDef a fill:#F1E8FF,stroke:#7B3FE4,color:#2A1458
+  classDef h fill:#FFF2E2,stroke:#E0861F,color:#4A2A05
+```
+
+<sub>Blue: the CLI (deterministic). Violet: your agent (judgement). Orange: you (one login, one batch of questions, one review).</sub>
+
+The fine-grained commands (`manifest`, `retrieve`, `facts`, `next`, `validate`…) are still there for CI and experts: `npx tadforce help --all`.
+
+## 📦 What you get
+
+| Deliverable | For | Contents |
+|---|---|---|
+| **Technical Architecture Document** — HTML | the client | Navigable, searchable, **edit in place**, **comment a passage or capture an area**, saved in the same file, export PDF / Word from the page |
+| **Technical Architecture Document** — PDF / DOCX | the client's archive | Print-ready A4 with page numbers; Word document from the same source; the version in the file name |
+| **Improvement Axes** — HTML / PDF / DOCX | the integrator | Measured signals per Well-Architected pillar, register `AX-nn`, roadmap — kept out of the client document |
+| `facts/facts.json` | everyone | The deterministic inventory of the org, byte-identical from one run to the next |
+
+The document carries **the client's logo and colours**: the logo is searched in the org (static resources, content assets, site assets) or given by you; the colours come from the org's Lightning theme, else from the logo — always readable (WCAG contrast checked). The integrator and the author are optional: leave them blank and the document names the client only.
+
+<div align="center">
+<img src="assets/gifs/review.gif" alt="Commenting a passage in the HTML and saving it into the same file" width="92%">
+<br><sub>The review loop: comment in the page, Save into the same file, then <code>/tadforce-review</code> resolves each comment and answers it.</sub>
+</div>
+
+## 🧩 Every kind of Salesforce project
+
+| 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) |
+| **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 |
+| **Unlocked or managed packages** | Namespaces and installed packages are detected and documented with their evidence |
+| **Any cloud, any industry** | Sections switch on only when the product is detected, each with its writing guide (below) |
+| **French or English** | Document, skeletons and interface in both; Salesforce terms stay in English |
+
+### Products and industries
+
+<table>
+<tr><td>
+
+**Clouds** · Sales Cloud · Service Cloud · Field Service · Experience Cloud · Marketing (Connect, Account Engagement) · Commerce & Order Management · CPQ, Billing, Revenue Cloud
+
+</td><td>
+
+**Industries** · Financial Services · Insurance · Health · Life Sciences · Manufacturing · Automotive · Consumer Goods · Communications / Media / Energy · Public Sector · Education · Nonprofit · Loyalty · Net Zero
+
+</td><td>
+
+**Platform** · OmniStudio · Data Cloud · Agentforce & Einstein · CRM Analytics · Platform Events & CDC · Shield · MuleSoft, Heroku, Slack, External Services
+
+</td></tr>
+</table>
+
+## 🏛️ The document model
+
+Every org gets **the same skeleton** — that is what makes two TADForce documents comparable:
+
+| # | Chapter | Highlights |
+|---|---|---|
+| — | Document control | Reference, version, classification, history (kept up to date by `update`) |
+| 1 | Executive summary | KPI tiles, capabilities, key achievements, principles |
+| 2 | Purpose, scope, references | Method, scope, exclusions applied, reading conventions |
+| 3 | Context and vision | Drivers, populations, functional scope, key figures |
+| 4 | General architecture | Generated context view, products with evidence, layered view, naming conventions |
+| 5 | Functional architecture | One section per business domain, with sequences and state diagrams |
+| 6 | Data | Generated ERDs (Lookup / Master-Detail only), external IDs, record types, Custom Metadata, events, volumes |
+| 7 | Application | Apex layers, triggers and order of execution, async, flows, OmniStudio, Agentforce, key sequences |
+| 8 | User interface | Apps, pages, LWC by domain, communication, sites, telephony and Omni-Channel |
+| 9 | Integrations | Patterns, `FLX-nn` flow catalogue, one section per connected system, inbound APIs, SSO |
+| 10 | Security | Personas and PSGs, generated role hierarchy, OWD, sharing, application security, Shield |
+| 11-15 | Reporting · Operations · NFR & Well-Architected · ADRs · Outlook | |
+| A-K | Appendices | Generated from facts: Apex, automation, objects, OmniStudio, UI, access, endpoints, packages, traceability, glossary |
+
+## 🔒 Read-only by design
+
+| Guarantee | How |
+|---|---|
+| Never changes the org | Every `sf` call goes through an allow-list: `org list/display/login`, `list metadata`, `retrieve`, `data query`, `config get`. `deploy`, `delete`, `apex run`… are refused. |
+| Never reads business data | SOQL guard: only org configuration objects, or aggregates (`COUNT()`, `MAX(CreatedDate)`, `GROUP BY` counts on users and assignments). |
+| Never touches your project | Retrieve goes to `tadforce/.snapshot` (git-ignored); `force-app` is untouched. |
+| Never leaks secrets | Credentials are never retrieved; `validate` blocks tokens, passwords, private keys and org IDs in the text. |
+
+### What leaves your machine
+
+The TADForce CLI sends nothing anywhere: no telemetry, no server, no account. It talks to your org through your own Salesforce CLI, and to the web only when **you** give it a logo URL. Your AI agent reads the metadata, the facts and the specifications you provide in order to write — exactly as when you ask it to read your code. Use the agent and the data-handling settings your company approved for client work.
+
+## 🎯 Reproducible by construction
+
+- **Facts are code, not prose.** `facts.json` is extracted deterministically (sorted, stable) — tested byte for byte.
+- **Numbers are placeholders.** Writers type `{{n:apex.classes}}`, never `132`. Tables, ERDs, role trees, KPIs and appendices are generated.
+- **Specs, not prompts.** 84 section specifications (`intent · facts · must · never`) drive every agent the same way.
+- **A gate, not a hope.** `npx tadforce validate` fails on unwritten sections, unknown placeholders, identifiers that do not exist in the org, excluded or decommissioned components, forbidden terms, broken anchors, Mermaid errors and secrets.
+- **Knowledge that sticks.** Client vocabulary, system names and exclusions live in `knowledge/*.yml`, so a regeneration never brings back a mistake a reader already fixed.
+
+## ⚔️ With vs without TADForce
+
+| | Writing by hand | A generic AI chat | **TADForce** |
+|---|---|---|---|
+| Time to a first complete draft | weeks | hours, then days of fact-checking | **an afternoon** |
+| Figures match the org | until the next release | rarely | **always — generated from facts** |
+| Same structure across clients | depends on the author | never | **always — one skeleton, 84 specs** |
+| System names and decommissioned features | tribal knowledge | hallucinated | **asked once, enforced forever** |
+| Client review | Word comments, copy-paste | — | **comments in the HTML, resolved by the agent** |
+| Three months later | start again | start again | **`update`: only what changed** |
+| Debt and risks | mixed with the description | mixed | **separate Improvement Axes document** |
+
+## 🧱 Built on
+
+[Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli) · [Agent Skills](https://agentskills.io) · [Salesforce skills (`forcedotcom/sf-skills`)](https://github.com/forcedotcom/sf-skills) · [Mermaid](https://mermaid.js.org) · [Puppeteer](https://pptr.dev) · [markdown-it](https://github.com/markdown-it/markdown-it) · [html2canvas](https://html2canvas.hertzen.com) · [html-docx-js](https://github.com/evidenceprime/html-docx-js)
+
+## 🗺️ Roadmap
+
+- [ ] More languages for the skeletons (es, de, pt, it)
+- [ ] Your own template: add, hide or rename chapters from `tadforce/templates/`
+- [ ] More examples: Service + Experience Cloud, an ISV package
+- [ ] Salesforce CLI plugin wrapper (`sf tad …`)
+- [ ] Dependency graph from `MetadataComponentDependency` (Tooling API)
+- [ ] Export to Confluence / SharePoint
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome — new product modules, new extractors, new languages. Read [CONTRIBUTING.md](CONTRIBUTING.md). Run `npm test` before opening a PR: it includes the unit tests and the genericity guard.
+
+## 👥 Community
+
+TADForce was born in the **Salesforce Architect Community Group of Casablanca**. Share your generated documents (anonymised!), your module ideas and your war stories in the issues. Star the repo if TADForce saved you a week. ⭐
+
+## 👤 Author
+
+<table>
+<tr>
+<td width="110"><img src="https://github.com/azamiji.png" width="96" alt="Jihad AZAMI HASSANI"></td>
+<td>
+
+**Jihad AZAMI HASSANI**<br>
+Salesforce Technical Architect, 10+ years of experience · Claude Certified Architect · Salesforce Architect Community Group Leader, Casablanca<br>
+[![Claude Certified Architect](https://img.shields.io/badge/Claude-Certified%20Architect-D97757?logo=claude&logoColor=white)](https://www.linkedin.com/in/jihadazami/)<br>
+[LinkedIn](https://www.linkedin.com/in/jihadazami/) · [GitHub](https://github.com/azamiji)
+
+</td>
+</tr>
+</table>
+
+## ⚖️ License
+
+[Apache-2.0](LICENSE) © Jihad AZAMI HASSANI.
+
+<sub>Salesforce, Sales Cloud, Service Cloud, Agentforce and the other product names are trademarks of Salesforce, Inc. TADForce is an independent community project, not affiliated with, sponsored or endorsed by Salesforce. The example organization (Northwind Bank, Acme Integrators) is fictional.</sub>