tadforce 0.0.0-stage → 0.2.0

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.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "tadforce",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "type": "module",
+  "bin": {
+    "tadforce": "bin/tadforce.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "skills",
+    "commands",
+    ".claude-plugin",
+    "assets/logo.svg",
+    "assets/logo-mark.svg",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\" && node tools/check-generic.js",
+    "test:unit": "node --test \"test/*.test.js\"",
+    "check:generic": "node tools/check-generic.js",
+    "example": "node bin/tadforce.js build --doc all --pdf --docx --cwd examples/northwind-bank",
+    "example:validate": "node bin/tadforce.js validate --doc all --cwd examples/northwind-bank",
+    "set-owner": "node tools/set-owner.js"
+  },
+  "keywords": [
+    "salesforce",
+    "architecture",
+    "technical-architecture-document",
+    "documentation",
+    "sfdx",
+    "sf-cli",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "well-architected",
+    "mermaid"
+  ],
+  "author": "Jihad AZAMI HASSANI (Salesforce Technical Architect)",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/azamiji/TADForce#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azamiji/TADForce.git"
+  },
+  "bugs": {
+    "url": "https://github.com/azamiji/TADForce/issues"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^4.5.0",
+    "markdown-it": "^14.1.0",
+    "puppeteer-core": "^23.11.1",
+    "yaml": "^2.6.1"
+  }
+}

package/skills/tadforce/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: tadforce
+description: Generate, end to end, a client-ready Technical Architecture Document (TAD) of any Salesforce org — plus the integrator's internal Improvement Axes — from the org's own metadata. Handles prerequisites, org authorization, wildcard manifest retrieve, deterministic facts, the questions only a human can answer, writing chapter by chapter, HTML (in-browser edit and comment) / PDF / DOCX build and validation. Covers every Salesforce product (Sales, Service, Field Service, Experience, Marketing, Commerce, Industries, CPQ/Revenue, OmniStudio, Data Cloud, Agentforce, CRM Analytics, Shield, integrations). Use when the user asks to document a Salesforce org, write or update an architecture document / solution architecture / as-built / document d'architecture technique, or runs /tadforce.
+---
+
+# TADForce — the architect's scribe
+
+You produce the architecture document a senior Salesforce architect would hand to a client: precise, evidence-based, readable, the same structure for every org. **No evidence, no sentence.**
+
+The CLI (`npx tadforce …`) does everything deterministic: org access, retrieve, facts, tables, diagrams from metadata, build, validation. You do what needs judgement: ask the right questions, read the code, write the narrative, keep the client's vocabulary.
+
+## Golden rules
+
+1. **Read-only.** Never deploy, never modify `force-app`, never read business records. TADForce only allows read-only `sf` commands and aggregate queries.
+2. **No evidence, no sentence.** Every statement relies on metadata (P1), a document provided by the project (P2/P3 — functional specifications are in `knowledge/inputs/specs/`), or is written as *to be confirmed*. See `references/evidence-rules.md`.
+3. **Never name a system by guessing.** External systems come from `knowledge/glossary.yml`, confirmed by a human. A field called `LegacyCoreId__c` does not tell you the system is called « Legacy Core ».
+4. **Never document what is decommissioned or excluded.** Ask about the candidates in `facts/questions.json`; record the answers in `knowledge/exclusions.yml`.
+5. **The client's vocabulary is law.** Apply `glossary.yml › terms` everywhere, diagrams included.
+6. **Numbers come from facts.** Write counts as `{{n:apex.classes}}`, links as `{{ref:section-id}}`. Never type a count by hand.
+7. **Client document ≠ internal review.** The TAD is factual and positive. Debt, risks and recommendations go to the Improvement Axes document.
+8. **Technical names in code font must exist** in the inventory (`tadforce validate` checks it).
+9. **Write in the document language** (`tadforce.config.json › language`). Keep Salesforce terms in English (Lead, Queue, Record Type, Named Credential…).
+10. **Ask in batches.** Group your questions; never ask what the facts already answer.
+
+## The run
+
+Four commands: **doctor → build → review → update**. Follow `references/workflow.md`. In short:
+
+| Step | You run | Human action |
+|---|---|---|
+| 1. Doctor | `npx tadforce doctor --json`, in a loop until `ok: true`. Answer its `questions` in one message (Block A of `references/questions.md`), then pass the answers as flags: `--confirm --lang … --client … --integrator …\|none --author …\|none --title … [--scope …] [--logo …] [--specs …\|--no-specs]`. Ask Blocks B–D, write `knowledge/*.yml`, then `--facts-reviewed` | log in once in the browser if asked; confirm the answers |
+| 2. Write | loop: `npx tadforce next --json` → read the spec, the facts, the specifications in `knowledge/inputs/specs/`, the code → replace the marker | — |
+| 3. Build | `npx tadforce build --pdf --docx` until validation shows 0 errors; hand over the paths, the score, the points to confirm | — |
+| 4. Review | `/tadforce-review` (`npx tadforce review --json`) | `npx tadforce review`: comment in the page, Save — always the same file |
+| Later | `/tadforce-update` (`npx tadforce update --json`) | — |
+
+## Writing a section
+
+`npx tadforce next --json` returns the file, the marker, and the spec: `intent`, `must`, `never`, `facts` (with an excerpt), and `readModules` (product references to read). Then:
+
+1. Read the facts excerpt; open the metadata or code files it points to (`tadforce/.snapshot/source/...` or `force-app/...`) when you need behaviour, not only names.
+2. Replace the `<!-- tad:pending id -->` line with the content. Keep the headings and their `{#id}` anchors.
+3. Use the conventions of `references/markdown-conventions.md`: `{{n:…}}`, `{{ref:…}}`, `@@ERD:…@@`, Mermaid + `Figure:` line, `> [!INTEGRATOR]`, cards and KPI blocks.
+4. Follow `references/writing-rules.md` (voice, structure, length) and `references/figure-rules.md`.
+5. Every few sections, run `npx tadforce validate` to catch unknown identifiers or forbidden terms early.
+
+## Products and industries
+
+`facts.modules.clouds` lists the products detected, each with its evidence and a reference under `references/modules/`. Read the reference of every detected product before writing chapters 4 to 11 — it says what to cover, where, and which pitfalls to avoid:
+
+`sales-cloud` · `service-cloud` · `field-service` · `experience-cloud` · `marketing` · `commerce` · `revenue-cpq` · `industries` · `omnistudio` · `data-cloud` · `agentforce-ai` · `analytics` · `platform-events` · `security-shield` · `integration-platforms`
+
+When a product is used but not detected (no metadata trace), the human tells you: add it to `glossary.yml › products` and cover it.
+
+## References
+
+- `references/workflow.md` — the full run, failure handling, long-running steps
+- `references/questions.md` — the exact questions to ask, in batches (EN / FR)
+- `references/evidence-rules.md` — levels of evidence, what counts as proof, when to ask
+- `references/writing-rules.md` — voice, structure and style of a consulting-grade TAD
+- `references/figure-rules.md` — when to draw, Mermaid conventions, generated figures
+- `references/markdown-conventions.md` — placeholders, directives, callouts, HTML blocks
+- `references/exclusion-heuristics.md` — unused / decommissioned components
+- `references/naming-external-systems.md` — glossary of systems and terms
+- `references/axes-rules.md` — the Improvement Axes document
+- `references/salesforce-skills.md` — Salesforce skills worth calling, and when
+- `references/modules/*.md` — one reference per Salesforce product family
+
+## Done means
+
+- `npx tadforce validate` → 0 error, warnings reviewed (each unknown identifier explained or fixed).
+- `tadforce/out/` holds the TAD (HTML, PDF, DOCX) and the Improvement Axes (HTML).
+- You give the human: the paths, the validation score, the sections you marked *to be confirmed*, and the questions still open.

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

@@ -0,0 +1,29 @@
+# The Improvement Axes document (internal to the integrator)
+
+Purpose: give the integrator an honest, prioritised view of the debt and the opportunities, separate from the client TAD. It may be shared with the client after review — write it so that it can be.
+
+## Inputs
+
+- `facts.signals` — measured signals (pillar, priority, value, evidence); tables are generated per pillar.
+- `knowledge/inputs/code-analyzer-results.json` — Code Analyzer violations (via the `dx-code-analyzer-run` skill).
+- The `platform-architecture-analyze` skill output (Well-Architected reading).
+- What you saw while writing the TAD (keep a scratch list of observations as you go).
+
+## Rules
+
+- A signal is not a finding. For each signal, decide: real issue, acceptable by design (say why), or false positive (drop it).
+- Each retained finding becomes an axis `AX-nn` with: finding (fact), impact (for the business or the run), recommendation (concrete, Salesforce-native), priority, effort (S / M / L).
+- Priorities: **P1** security, data integrity or continuity at risk; **P2** plan in the next releases (maintainability, limits, retired features such as Workflow Rules and Process Builder); **P3** improve when touching the area.
+- Pillars follow Salesforce Well-Architected: Trusted, Easy, Adaptable.
+- Name components; never people or teams.
+- No duplicates with the TAD: the TAD describes, the Axes document improves. The TAD's outlook chapter may point to this document without quoting it.
+
+## Register table
+
+| ID | Axis | Finding | Impact | Recommendation | Priority | Effort |
+|---|---|---|---|---|---|---|
+| AX-01 | Sharing | 3 classes declared `without sharing` serve UI controllers | Users may read records beyond their access | Switch to `with sharing` + `WITH USER_MODE`; keep `without sharing` in a dedicated system class | <span class="b p1">P1</span> | M |
+
+## Roadmap
+
+Group the axes by horizon (next release, next quarter, next year) or by theme; a Mermaid `gantt` is welcome.

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

@@ -0,0 +1,40 @@
+# Evidence rules — no evidence, no sentence
+
+## Levels of evidence
+
+| Level | Source | Example | How to write it |
+|---|---|---|---|
+| **P1** | Metadata or code of the org | `LeadTrigger` calls `LeadTriggerHandler.run()` | State it as a fact |
+| **P2** | Technical document provided by the project | Release procedure in `knowledge/inputs/` | State it as a fact; cite the reference (DR-nn) when it matters |
+| **P3** | Functional document, ticket, interview | « Advisors handle 30 leads a day » | Attribute it: « according to the specifications (DR-01) » |
+| **To confirm** | Deduction, missing or contradictory information | Retention policy not configured in the org | Write « to be confirmed » / « à confirmer » and list it in your hand-over |
+
+## Kinds of statements
+
+Keep them apart in your head and in the text:
+
+- **Documented requirement** — written in a specification.
+- **Technical observation** — visible in the metadata or the code.
+- **Deduction** — logical but not proven: say so, or leave it out.
+- **Unavailable information** — absent from the snapshot: say it is not visible, never fill the gap.
+- **Recommendation** — goes to the Improvement Axes, not to the TAD.
+
+## Non-equivalences
+
+- A name that looks like a business term is not a proof of the link (`LegacyCoreId__c` does not mean the system is called « Legacy Core »).
+- Absent from the snapshot ≠ absent from the org (a type may have failed to retrieve: check `.snapshot/retrieve-report.json`).
+- Present in the snapshot ≠ used (inactive flows, components placed nowhere, objects with no record).
+- A ticket status or a file date is not a proof of deployment.
+- What a Salesforce product *can* do is not what this org *does*.
+
+## Reading code for evidence
+
+- Read the handler, not only the trigger; the service, not only the controller.
+- Note thresholds and switches (`if (records.size() > 200) Database.executeBatch…`), named credentials (`callout:X`), custom metadata read (`X__mdt.getAll()`), platform events published (`EventBus.publish`).
+- For flows: start element (object, trigger type), decisions, actions (Apex, subflows), record operations.
+- For OmniStudio: OmniScript elements → Integration Procedure → Data Mapper / Remote Action / HTTP.
+- Keep a short list of `file:line` for the sentences that matter; you need it when the human challenges a statement.
+
+## When to ask
+
+Ask when a sentence would otherwise rely on a guess about: the name of a system, the use of a component that looks dead, a decommissioned feature, an environment or a release step, a number not in facts. Batch the questions (`questions.md`).

package/skills/tadforce/references/exclusion-heuristics.md

@@ -0,0 +1,40 @@
+# Unused and decommissioned components
+
+An org accumulates proofs of concept, test scaffolding, samples and features switched off but still deployed. Documenting them misleads the reader; deleting them is not your job. TADForce **proposes** candidates; the human **decides**; the decision lives in `knowledge/exclusions.yml`.
+
+## Candidates computed by `tadforce facts`
+
+| Reason | Meaning | Typical decision |
+|---|---|---|
+| name suggests test / demo / POC / sample / old / legacy / draft… | Words in the API name | Exclude after a quick look |
+| not placed on any page, app, tab, action, flow or OmniStudio component | LWC or Aura never used in the snapshot | Exclude unless used by a site or a utility bar outside the snapshot |
+| flow status is Draft / Inactive / Obsolete | No active version | Exclude |
+| inactive version (OmniStudio) | No active OmniScript / IP / Data Mapper version | Exclude |
+| referenced only by test classes | Apex reached by nothing but its tests | Ask: often dead code, sometimes started by anonymous Apex or a scheduler |
+| not referenced by any other component | Apex not reached at all (entry points such as REST, schedulable, invocable, global, SSO handlers are never flagged) | Ask |
+| not assigned to any app, object override or tab | FlexiPage not assigned in the snapshot | Ask: assignments by profile may live outside the snapshot |
+| object with no record in the org | From org facts | Ask: new feature not live yet, or abandoned |
+
+## Exclusions file
+
+```yaml
+exclude:
+  - name: "*Demo*"               # wildcard on the API name
+    reason: "Demonstration components"
+  - name: legacyScoring
+    type: lwc                    # optional: apex, trigger, lwc, aura, flow, flexipage, app, object, permissionSet, omniScript, integrationProcedure, dataMapper, report, emailTemplate, staticResource…
+    reason: "Replaced by the scoring engine"
+features:
+  - name: "Search by national ID"
+    note: "UI removed; backend kept until further notice"
+    components: [idSearch, IdSearchController, IdSearch_Procedure]
+    keywords: ["national ID search", "ID card search"]   # forbidden in the text
+```
+
+- Excluded components disappear from every count, table and figure after `tadforce facts`.
+- `features.keywords` are forbidden in the text: `tadforce validate` fails if one appears.
+- The method section of the TAD lists the exclusions applied (generated), so the client knows what was left out and why.
+
+## In the Improvement Axes
+
+Candidates that the human did not exclude but did not confirm either are listed in the appendix of the Improvement Axes: cleaning them is an improvement axis, never a TAD statement.

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

@@ -0,0 +1,42 @@
+# Figure rules
+
+A figure is worth its place only when it shows a relationship, a branch, an order or a dependency that text cannot show at a glance.
+
+## Generated figures (do not draw them by hand)
+
+| Directive | What it draws |
+|---|---|
+| `@@FIGURE:context@@` | Context view: users (glossary.actors or apps), the org with its products, connected systems |
+| `@@FIGURE:layers@@` | Logical layers with counts |
+| `@@FIGURE:integrations\|caption@@` | Integration map from glossary systems and endpoints |
+| `@@FIGURE:roles\|caption@@` | Role hierarchy (top levels on large orgs) |
+| `@@ERD:Obj1,Obj2,…\|caption@@` | ER diagram, Lookup / Master-Detail fields only; `@@ERD:auto\|caption@@` picks the most connected objects |
+
+## Hand-written Mermaid figures
+
+Fence them as `mermaid` and put the caption on the line right after the closing fence:
+
+    ```mermaid
+    sequenceDiagram
+      participant U as Advisor
+      participant L as customer360
+      U->>L: open the customer record
+    ```
+    Figure: Opening the customer 360 view
+
+- **Sequences** (`sequenceDiagram`): only calls you saw in code or metadata. Participants are components or confirmed systems. 4 to 9 participants, 6 to 15 messages. Numbering is automatic.
+- **Flowcharts** (`flowchart LR|TB`): use the shared classes `:::actor`, `:::sf`, `:::ext`, `:::data`, `:::warn` (added automatically). Node ids short and alphanumeric (`A1`), labels in double quotes: `A1["Lead (web)"]:::actor`.
+- **State diagrams** (`stateDiagram-v2`) for statuses with transitions.
+- **Gantt** only in the Improvement Axes roadmap.
+- ERDs are never hand-written: use `@@ERD@@` so they match the metadata.
+
+## Mermaid pitfalls (they break the build)
+
+- Parentheses, brackets, `#`, `;` or quotes inside an unquoted label → always quote labels.
+- `end` as a node id; a `-->` inside a label; `:` inside sequence messages is fine, `;` is not.
+- Long labels: wrap with `<br/>` is not supported (labels are SVG text) — keep labels short instead.
+- One diagram per fence; the `Figure:` line must follow the fence immediately.
+
+## Captions
+
+Sentence case, no final full stop, say what the figure shows: « Figure: Lead lifecycle, from the sources to conversion or archiving ».

package/skills/tadforce/references/markdown-conventions.md

@@ -0,0 +1,67 @@
+# Markdown conventions of TADForce sources
+
+The sources live in `tadforce/src/tad/*.md` and `tadforce/src/axes/*.md`, concatenated in file-name order.
+
+## Headings
+
+- `#` chapter, `##` section, `###` subsection — numbered automatically (1, 1.2, 1.2.3).
+- `{-}` at the end: not numbered. `{#my-id}`: explicit anchor. Both: `{- #my-id}`.
+- In appendices, `{{letter}}` in a `##` title becomes A, B, C… and `{{sub}}` in a `###` becomes A.1, A.2… so optional appendices never leave gaps.
+- Keep the anchors of the skeleton: KPI tiles, references and validation rely on them.
+
+## Placeholders (resolved at build)
+
+| Placeholder | Result |
+|---|---|
+| `{{n:apex.classes}}` | Formatted number from `facts.counts` (then from the facts root) |
+| `{{v:modules.products}}` | Raw value from facts |
+| `{{cfg:client.name}}` | Value from `tadforce.config.json` |
+| `{{ref:data-overview}}` | Link « § 6.2 » to the section |
+| `{{title:ch-data}}` | Link « 6 Data architecture » |
+
+Main count keys: `apex.classes`, `apex.tests`, `apex.triggers`, `apex.batch`, `apex.queueable`, `apex.schedulable`, `apex.future`, `apex.rest`, `apex.withSharing`, `apex.withoutSharing`, `objects.custom`, `objects.standard`, `objects.platformEvents`, `fields.custom`, `fields.externalIds`, `recordTypes`, `validationRules.active`, `cmdt.types`, `cmdt.records`, `flows.active`, `flows.recordTriggered`, `flows.scheduled`, `omni.scriptsActive`, `omni.ipsActive`, `omni.dataMappers`, `ui.apps`, `ui.flexipages`, `ui.lwc`, `ui.aura`, `ui.vfPages`, `security.profiles`, `security.permissionSets`, `security.permissionSetGroups`, `security.roles`, `security.queues`, `security.sharingRules`, `integration.namedCredentials`, `integration.externalCredentials`, `integration.restResources`, `integration.connectedApps`, `integration.systems`, `misc.reports`, `misc.dashboards`, `misc.labels`.
+
+## Directives (one per line)
+
+- `@@ANNEX:<name>@@` — generated table. Names: `doc-control`, `version-history`, `legend`, `key-figures`, `products`, `naming`, `objects`, `standard-objects`, `external-ids`, `record-types`, `validation-rules`, `cmdt`, `platform-events`, `volumes`, `apex-summary`, `triggers`, `async`, `rest`, `flows`, `omni-scripts`, `integration-procedures`, `data-mappers`, `apps`, `flexipages`, `lwc`, `aura`, `visualforce`, `psg`, `permission-sets`, `profiles`, `roles`, `owd`, `sharing-rules`, `queues`, `named-credentials`, `external-credentials`, `connected-apps`, `auth-providers`, `allowed-domains`, `call-centers`, `systems`, `reports`, `labels`, `scheduled-jobs`, `packages`, `exclusions`, `inventory`, `traceability`, `glossary`, `signals`, `signals-trusted`, `signals-easy`, `signals-adaptable`, `exclusion-candidates`.
+- `@@ERD:Obj1,Obj2|caption@@`, `@@FIGURE:context|layers|integrations|roles@@`, `@@KPIS@@`.
+- `@@INCLUDE:knowledge/figures/x.svg@@` — include a file (SVG figures are framed). Follow it with `<p class="figcap">Figure — caption</p>` to number it.
+
+## Conditional blocks
+
+```
+<!-- tad:if modules.omnistudio -->
+…only when OmniStudio is detected…
+<!-- tad:else -->
+…otherwise…
+<!-- tad:endif -->
+```
+
+Conditions are facts paths (`modules.*`, `counts.*`, `org.*`, `facts.*`), `!` negates, `a|b` means either.
+
+## Callouts
+
+```
+> [!INTEGRATOR]
+> The scoring rules are Custom Metadata records: a new rule needs no deployment.
+```
+
+Kinds: `INTEGRATOR` (the integrator's contribution), `NOTE`, `RECO` (rare in the TAD), `WARN`.
+
+## HTML blocks
+
+Cards (achievements):
+
+```html
+<div class="cards">
+<div class="card"><h4>Title</h4><p>Two to four sentences with `code` replaced by <code>code</code>.</p></div>
+</div>
+```
+
+Markdown is not processed inside HTML blocks: use `<code>`, `<b>`, `<a href="#id">`.
+
+Priority badges (Improvement Axes): `<span class="b p1">P1</span>`, `p2`, `p3`.
+
+## Pending markers
+
+`<!-- tad:pending <id> -->` marks a section to write. Replace the whole line. `tadforce next` gives the next one; `tadforce validate` fails while active ones remain.

package/skills/tadforce/references/modules/agentforce-ai.md

@@ -0,0 +1,24 @@
+# Agentforce and Einstein
+
+**Detected by** `bots` / `botVersions`, `genAiPlanners`, `genAiPlannerBundles`, `genAiPlugins` (topics), `genAiFunctions` (actions), `aiAuthoringBundles` (Agent Script), `genAiPromptTemplates`, Einstein prediction definitions.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 7 Application | `application.ai` section: each agent (purpose, channel, topics, actions and what they call — Flow, Apex, prompt template, API), grounding sources (knowledge, Data Cloud, records), guardrails and escalation to humans, prompt templates and where they are used, Einstein features used (scoring, classification, Copilot features) |
+| 8 UI | Where agents appear (Lightning, Experience site, messaging channel) |
+| 10 Security | Agent user, permission sets, Einstein Trust Layer settings, data masking |
+| 12 Operations | Testing (agent tests), monitoring (session tracing, health alerts) |
+
+## Read
+
+Agent metadata above; the `agentforce-architecture-analyze` skill renders the declared architecture of one agent (topics, actions, flows, Apex, prompts).
+
+## Draw
+
+Flowchart agent → topics → actions → Flow / Apex / prompt template → data.
+
+## Watch out
+
+Describe declared behaviour, never transcripts or user prompts. Legacy Einstein Bots and Agentforce agents may coexist: say which channel uses which.

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

@@ -0,0 +1,19 @@
+# CRM Analytics and Tableau
+
+**Detected by** `wave*` metadata (applications, dashboards, dataflows, recipes, datasets) or namespace `wave`; Tableau shows as CSP trusted sites or embedded LWC.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 11 Reporting | `reporting.analytics` section: apps and their audience, data preparation (dataflows or recipes, schedules, sources), datasets, dashboards embedded in Lightning pages, security predicates and sharing inheritance |
+| 9 Integrations | External data sources and connectors |
+| 10 Security | Analytics permission sets and licences, row-level security |
+
+## Read
+
+`waveApplications`, `waveDashboards`, `waveDataflows`, `waveRecipes`, `waveDatasets` (XMD), flexipages embedding analytics components.
+
+## Watch out
+
+Lightning reports and dashboards (chapter 11 first section) and CRM Analytics are distinct: document both when both exist.

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

@@ -0,0 +1,25 @@
+# Commerce (B2B / D2C on Lightning, B2C Commerce connector, Order Management)
+
+**Detected by** `WebStore`, `WebCart`, `ProductCatalog`, `BuyerGroup`, `BuyerAccount`, entitlement policies; Order Management by `OrderSummary`, `FulfillmentOrder`, `ReturnOrder`.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 5 Functional | Buyer journey (browse, search, cart, checkout, payment, order), account management, reorder; order lifecycle (summary, fulfilment, returns, refunds) |
+| 6 Data | Catalog and categories, products and price books, buyer groups and entitlements, carts, orders and order summaries |
+| 8 UI | Store site (LWR template, components), search configuration, guest browsing |
+| 9 Integrations | Checkout integrations (pricing, inventory, shipping, tax, payment gateway), ERP for orders and stock, product information management |
+| 10 Security | Buyer licences, store guest access, payment data never stored in Salesforce |
+
+## Read
+
+`objects/WebStore` and commerce objects, store `experiences`/`digitalExperiences`, Apex classes implementing commerce extension points (`commercestorefront`, `sfdc_checkout.*` interfaces), named credentials of payment and tax providers, flows of the checkout.
+
+## Draw
+
+Sequence of checkout with each external call; state diagram of the order summary.
+
+## Watch out
+
+B2C Commerce (Salesforce Commerce Cloud on its own platform) is a separate system: treat it as an external system unless the documents say otherwise.

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

@@ -0,0 +1,23 @@
+# Data Cloud
+
+**Detected by** data stream definitions, data model objects (`__dlm`), data lake objects (`__dll`), Data Cloud metadata folders.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 6 Data | Data streams (sources: CRM, ingestion API, cloud storage, Marketing Cloud), data lake and data model objects, mappings, identity resolution rulesets, calculated insights, segments |
+| 9 Integrations | Ingestion connectors and activation targets (Marketing, advertising, CRM), data actions and data graphs used by the CRM (related lists, Agentforce grounding) |
+| 10 Security | Data spaces, permission sets for Data Cloud, consent |
+
+## Read
+
+`dataStreamDefinitions`, `dataSourceObjects`, `__dlm` / `__dll` objects, `mktCalcInsightObjectDefs`, data graphs, `dataSpaces`; the `data360-schema-get` skill helps.
+
+## Draw
+
+Flowchart sources → data streams → DLO → DMO → identity resolution → segments / insights → activations.
+
+## Watch out
+
+Data Cloud configuration is partly outside the metadata API: say what you could not see. Never quote profile data.

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

@@ -0,0 +1,24 @@
+# Experience Cloud (sites and portals)
+
+**Detected by** `networks`, `experiences` / `digitalExperiences` bundles, `sites`, `navigationMenus`.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 3 Context | External populations (customers, partners, citizens, employees) and their channel |
+| 8 UI | One `###` per site: audience, template (LWR or Aura), pages and custom components, navigation, branding, languages, mobile |
+| 9 Integrations | Identity (self-registration, SSO, social login), embedded services (messaging), CMS content |
+| 10 Security | Licences (Customer Community, Partner Community…), sharing sets and share groups, guest user access and its sharing rules, external OWD, CSP/CORS for the site, clickjack and session settings |
+
+## Read
+
+`networks/*.network-meta.xml` (self-registration, login, member profiles), `experiences` / `digitalExperiences` (routes, views, components used), `sites`, `sharingSets`, guest sharing rules (`sharingGuestRules`), profiles with community licences, `navigationMenus`, `cspTrustedSites`.
+
+## Draw
+
+Context view of the site (external users ↔ site ↔ org ↔ systems); sequence of self-registration or login.
+
+## Watch out
+
+Guest user access is a security topic: describe it factually in the TAD, put any overexposure in the Improvement Axes. External OWD differs from internal OWD.

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

@@ -0,0 +1,25 @@
+# Field Service
+
+**Detected by** namespace `FSL`, or customised `WorkOrder`, `ServiceAppointment`, `ServiceTerritory`, `ServiceResource`, `MaintenancePlan`.
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 5 Functional | Work order lifecycle (creation from case or asset, work types, line items), scheduling and dispatch (policies, optimisation), mobile execution (Field Service mobile app, flows, data capture), completion and billing triggers; preventive maintenance plans |
+| 6 Data | Work order / appointment / assigned resource model, territories and operating hours, skills, products consumed and required, assets |
+| 7 Application | Scheduling policies and work rules (`FSL` objects are data, not metadata: ask), automation on appointment status changes |
+| 8 UI | Dispatcher console, Gantt, mobile app configuration (offline priming) |
+| 10 Security | Field service permission sets, territory-based sharing, mobile user licences |
+
+## Read
+
+`objects/WorkOrder`, `objects/ServiceAppointment`, `objects/ServiceTerritory`, `objects/ServiceResource`, `workTypes`, `FSL__*` references, mobile app extensions (`lwc` with `lightning__GlobalAction` targets), flows launched from the mobile app.
+
+## Draw
+
+State diagram of appointment statuses; sequence case → work order → appointment → dispatch → mobile completion.
+
+## Watch out
+
+Scheduling policies, work rules and service objectives are records in `FSL` objects: they are not in the metadata; ask for them or describe them as configuration to confirm.

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

@@ -0,0 +1,21 @@
+# Industry clouds
+
+**Detected by** namespaces or standard industry objects (see `facts.modules.clouds` evidence): Financial Services (`FinServ`, `FinancialAccount`, `ResidentialLoanApplication`), Insurance (`InsurancePolicy`, `Claim`), Health (`HealthCloudGA`, `CarePlan`, `ClinicalEncounter`), Life Sciences, Manufacturing (`SalesAgreement`, `AccountForecast`), Automotive (`Vehicle`), Consumer Goods (`RetailStore`, `Visit`), Communications / Media / Energy & Utilities (`vlocity_cmt`, `ServicePoint`), Public Sector (`IndividualApplication`, `BusinessLicense`), Education (`hed`, `LearnerProfile`), Nonprofit (`npsp`, `GiftTransaction`), Loyalty (`LoyaltyProgram`), Net Zero (carbon footprint objects).
+
+## Document
+
+| Chapter | What |
+|---|---|
+| 4 General | Which industry cloud, which data model version (managed package vs standard objects), which industry features are used (and which are not) |
+| 5 Functional | The industry processes as implemented (examples: onboarding and financial accounts; policy and claims; care plans and referrals; sales agreements and account forecasts; retail execution visits; licensing and permits; admissions and advising; donations and programs; loyalty accrual and redemption) |
+| 6 Data | The industry objects used, with their role and what is custom around them (`data.industry` section); Person Accounts and household or group models |
+| 7 Application | Industry engines used: OmniStudio, Business Rules Engine (decision matrices, expression sets), Document Generation, Action Plans, Industries Interaction Summaries — each only if seen in the metadata |
+| 10 Security | Compliant data sharing (`participant`-based sharing), industry permission set licences |
+
+## Read
+
+Objects with the namespace or industry standard names, `decisionMatrixDefinitions` and `expressionSetDefinitions` (Business Rules Engine), `actionPlanTemplates`, `documentTemplates`, OmniStudio assets, Person Account settings (`settings/Account.settings-meta.xml`).
+
+## Watch out
+
+Industry clouds ship hundreds of objects: document only those referenced by local metadata or customised. Data model versions differ (managed package `FinServ__` vs core standard objects): say which one the org uses.