tadforce 0.0.0-stage → 0.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "tadforce",
+  "owner": {
+    "name": "Jihad AZAMI HASSANI"
+  },
+  "metadata": {
+    "description": "TADForce — AI-Powered Salesforce Technical Documentation, written by your agent from the org's own metadata."
+  },
+  "plugins": [
+    {
+      "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",
+      "author": { "name": "Jihad AZAMI HASSANI" },
+      "license": "Apache-2.0",
+      "category": "documentation"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "tadforce",
+  "version": "0.3.0",
+  "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",
+    "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.md

@@ -1,3 +1,267 @@
-# 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%">
+
+### AI-Powered Salesforce Technical Documentation
+
+**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)
+
+</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) |
+| **Any language** | English and French built in. Any other language (Spanish, German, Italian, Portuguese, Arabic, Japanese…): pick it in `doctor`, your agent translates the headings and labels once, then writes in that language. 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
+
+- [ ] Built-in skeletons for more languages (es, de, pt, it) — any language already works through the agent; contributions welcome
+- [ ] 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 for the **Salesforce ecosystem**: architects, consultants, integrators and in-house teams who need documentation they can trust.
+
+Your experience is what makes it better. Tell us, in the [issues](https://github.com/azamiji/TADForce/issues) and [discussions](https://github.com/azamiji/TADForce/discussions):
+
+- **How it went** — the kind of org and project, the time it took, what worked out of the box.
+- **How good the result was** — sections that read like a senior architect wrote them, and sections that did not.
+- **What to improve** — a product it should detect better, a section that misses the point, a question it should have asked.
+
+Please share your feedback, not your documents: they describe your clients' systems.
+
+If TADForce saved you a week, **star the repo** ⭐ — it is how other Salesforce teams find it.
+
+## 👤 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>

package/assets/logo-mark.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128" role="img" aria-label="TADForce">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1E88FF"/>
+      <stop offset="1" stop-color="#9B1FE8"/>
+    </linearGradient>
+    <pattern id="grid" width="12" height="12" patternUnits="userSpaceOnUse">
+      <path d="M12 0H0V12" fill="none" stroke="#ffffff" stroke-opacity=".16" stroke-width="1"/>
+    </pattern>
+  </defs>
+  <rect width="128" height="128" rx="30" fill="url(#g)"/>
+  <rect width="128" height="128" rx="30" fill="url(#grid)"/>
+  <!-- blueprint sheet with a folded corner -->
+  <path d="M38 20h38l20 20v62a6 6 0 0 1-6 6H38a6 6 0 0 1-6-6V26a6 6 0 0 1 6-6z" fill="#ffffff"/>
+  <path d="M76 20v14a6 6 0 0 0 6 6h14z" fill="#D6E4FF"/>
+  <!-- the T: crossbar + compass legs -->
+  <path d="M44 50h40" stroke="#0B2545" stroke-width="7" stroke-linecap="round"/>
+  <path d="M64 52L55 96" stroke="#0B2545" stroke-width="6" stroke-linecap="round"/>
+  <path d="M64 52L73 96" stroke="#0B2545" stroke-width="6" stroke-linecap="round"/>
+  <circle cx="64" cy="52" r="6.5" fill="#9B1FE8" stroke="#0B2545" stroke-width="3"/>
+  <!-- the line the compass draws -->
+  <path d="M50 100q14 7 28 0" fill="none" stroke="#9B1FE8" stroke-width="3" stroke-linecap="round" stroke-dasharray="2 5"/>
+  <path d="M44 34h18M44 40h12" stroke="#1E88FF" stroke-width="3" stroke-linecap="round" opacity=".55"/>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 128" width="700" height="128" role="img" aria-label="TADForce">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1E88FF"/>
+      <stop offset="1" stop-color="#9B1FE8"/>
+    </linearGradient>
+    <linearGradient id="t" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#1E88FF"/>
+      <stop offset="1" stop-color="#9B1FE8"/>
+    </linearGradient>
+    <pattern id="grid" width="12" height="12" patternUnits="userSpaceOnUse">
+      <path d="M12 0H0V12" fill="none" stroke="#ffffff" stroke-opacity=".16" stroke-width="1"/>
+    </pattern>
+  </defs>
+  <g>
+    <rect width="128" height="128" rx="30" fill="url(#g)"/>
+    <rect width="128" height="128" rx="30" fill="url(#grid)"/>
+    <path d="M38 20h38l20 20v62a6 6 0 0 1-6 6H38a6 6 0 0 1-6-6V26a6 6 0 0 1 6-6z" fill="#ffffff"/>
+    <path d="M76 20v14a6 6 0 0 0 6 6h14z" fill="#D6E4FF"/>
+    <path d="M44 50h40" stroke="#0B2545" stroke-width="7" stroke-linecap="round"/>
+    <path d="M64 52L55 96" stroke="#0B2545" stroke-width="6" stroke-linecap="round"/>
+    <path d="M64 52L73 96" stroke="#0B2545" stroke-width="6" stroke-linecap="round"/>
+    <circle cx="64" cy="52" r="6.5" fill="#9B1FE8" stroke="#0B2545" stroke-width="3"/>
+    <path d="M50 100q14 7 28 0" fill="none" stroke="#9B1FE8" stroke-width="3" stroke-linecap="round" stroke-dasharray="2 5"/>
+    <path d="M44 34h18M44 40h12" stroke="#1E88FF" stroke-width="3" stroke-linecap="round" opacity=".55"/>
+  </g>
+  <text x="152" y="82" font-family="Segoe UI, Inter, Helvetica Neue, Arial, sans-serif" font-size="64" font-weight="800" letter-spacing="-1.5">
+    <tspan fill="#0B2545">TAD</tspan><tspan fill="url(#t)">Force</tspan>
+  </text>
+  <text x="155" y="110" font-family="Segoe UI, Inter, Helvetica Neue, Arial, sans-serif" font-size="14" font-weight="600" fill="#5a6878" letter-spacing="2">THE ARCHITECT'S SCRIBE · NO EVIDENCE, NO SENTENCE</text>
+</svg>

package/bin/tadforce.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/commands/tadforce-review.md

@@ -0,0 +1,8 @@
+---
+description: Apply the review comments saved in a TADForce HTML document and rebuild it with the comments resolved
+argument-hint: "[path to the saved HTML]"
+---
+
+Use the `tadforce-review` skill. Comments file: $ARGUMENTS (default: `tadforce/out/TAD_<CODE>.html`, the single file the readers comment through `npx tadforce review`).
+
+List the open comments with `npx tadforce review --json`, classify them, apply each correction to the sources and to the knowledge files, record the resolutions in `tadforce/tadforce.config.json`, rebuild with `npx tadforce build --pdf --docx`, and report one line per comment.

package/commands/tadforce-update.md

@@ -0,0 +1,6 @@
+---
+description: Bring an existing Technical Architecture Document up to date with what changed in the org since its last version
+argument-hint: "[org alias]"
+---
+
+Use the `tadforce-update` skill. Run `npx tadforce update --json`, rewrite only the sections it lists from the new facts and the changed metadata, rebuild with `npx tadforce build --pdf --docx`, and report what changed in the document.

package/commands/tadforce.md

@@ -0,0 +1,10 @@
+---
+description: Generate the Technical Architecture Document (and the Improvement Axes) of the current Salesforce org, end to end
+argument-hint: "[org alias] [fr|en]"
+---
+
+Use the `tadforce` skill to produce the Technical Architecture Document of this Salesforce project, end to end: `doctor` (tools, org connection, metadata, the questions only a human can answer), writing every section, `build` (HTML with editing and comments, PDF, DOCX) and validation, then the Improvement Axes document.
+
+Arguments (optional): $ARGUMENTS — an org alias and/or the document language.
+
+Start with `npx tadforce doctor --json` and loop on it until `ok: true`, following `skills/tadforce/references/workflow.md`. Ask the framing questions in one batch, each with its recommended answer. Stop only when `npx tadforce validate` reports 0 errors, then hand over the paths, the score and the points to confirm.