@tidyfactor/doc 1.3.0 → 1.9.0

package/.tidyfactor

@@ -1,8 +1,8 @@
 {
   "name": "tidyfactor-doc",
-  "version": "1.3.0",
-  "category": "architecture",
-  "description": "TidyFactor Doc - Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify)",
+  "version": "1.9.0",
+  "category": "development",
+  "description": "TidyFactor Doc — Code Documentation Builder, ADR Architect, Link Auditor & Triple-Engine Publishing Platform (VitePress, MkDocs Material & Docsify) for AI Coding Agents",
   "repository": "https://github.com/TidyFactor/Doc",
   "npm": "@alwkala/tidyfactor-doc",
   "compatibility": [

package/CHANGELOG.md

@@ -3,11 +3,110 @@
 All notable changes to `tidyfactor-doc` will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## [1.2.1] - 2026-08-25
+## [1.9.0] - 2026-09-09
 
-### Fixed
-- **CLI Executable & NPX Packaging**: Added standard `"add-skill": "bin/add-skill.js"` mapping in `package.json` to ensure unified `npx @tidyfactor/cli-doc add-skill` execution.
-- **Workflow Compliance**: Standardized `## Validation checklist` headers across all 8 workflows.
+### 🚀 Added — Architectural Decision Records (ADR), Deep Docblock Scraping, Project Mindmaps & Asset Hygiene
+- **Architectural Decision Record Generator (`references/commands/adr.md`, `references/workflows/generate-adr.md`)**:
+  - Added dedicated `adr` command with Context-Aware prompts to record technical choices, problem context, decision drivers, and consequences.
+  - Standardized on MADR (Markdown Architectural Decision Records) schema with index generation (`docs/adr/README.md`).
+- **Deep Code Parsing in Collect Workflow (`references/workflows/collect.md`)**:
+  - Enriched Step 1 with automated scraping for PHPDoc (`@param`, `@return`, `@throws`, `@deprecated`) and JSDoc/TSDoc (`@param`, `@returns`, `@typedef`, `@template`) annotations.
+  - Mapped AST interface types and class properties directly to documentation templates.
+- **Operational Memory Expansion**:
+  - Added `references/memory/adr-template.md`: Authoritative MADR record structure and master table of contents.
+  - Added `references/memory/project-mindmap.md`: Mermaid AST schemas for architecture layering, component topologies, and execution flows.
+  - Added `references/memory/naming-conventions.md`: Uniform naming conventions across PHP (PSR-1/PSR-12), TypeScript, Python, and doc slugs.
+  - Added `references/memory/tone-of-voice.md`: Non-negotiable technical writing rules (direct, action-oriented, zero marketing fluff).
+  - Added `references/memory/git-doc-sync-hook.md`: Pre-commit hook specification enforcing documentation updates alongside core code changes.
+- **Automated Asset Hygiene & Orphan Detection (`scripts/clean_orphaned_assets.py`)**:
+  - Added script to scan all `.md` files for image references, identify unreferenced assets in `assets/`, detect duplicate files via SHA-256 hashes, and calculate WebP compression savings.
+- **Unified Tooling Manifest (`manifest.json`)**:
+  - Registered `clean_orphaned_assets` tool with portable CLI patterns.
+  - Registered `adr` command in tool invocation mappings and decision gate options.
+
+---
+
+## [1.8.0] - 2026-09-09
+
+### 🚀 Added — Documentation Hygiene Auditor, Keep a Changelog Architecture & Asset Optimization
+- **Documentation Quality & Link Auditor (`references/commands/audit.md`, `references/workflows/audit.md`)**:
+  - Added dedicated `audit` command and workflow for sub-second deterministic doc scanning.
+  - Added relative markdown link integrity verification in `scripts/audit_docs.py` (`check_relative_links`) to detect broken local file links before release.
+  - Added Keep a Changelog structural validator (`check_changelog_format`) verifying SemVer release headers and standard change categories.
+- **Changelog Workflow & SSOT Architecture (`references/workflows/generate-changelog.md`)**:
+  - Codified automated `generate-changelog` workflow strictly adhering to Keep a Changelog v1.1.0 and SemVer 2.0.0.
+  - Conventional Commits parser mapping git commits to standard sections (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`).
+  - Integrated changelog generation routing into `references/commands/generate.md`.
+- **Operational Memory & Governance Templates (`references/memory/changelog-rules.md`, `references/memory/doc-templates.md`)**:
+  - Added `references/memory/changelog-rules.md` establishing release standards, SemVer bump formulas, and conventional commit mappings.
+  - Added standard `CHANGELOG.md` template to `references/memory/doc-templates.md`.
+  - Refreshed all memory verification timestamps (`<!-- last-verified: 2026-09-09 -->`).
+- **Asset Deduplication & Hygiene (`assets/`)**:
+  - Removed duplicate 242KB asset (`assets/og-default.png`), saving 50% of the asset footprint without breaking references.
+- **Unified Tooling & Decision Manifest (`manifest.json`)**:
+  - Expanded `audit_docs` tool contract with link integrity and changelog validation scopes.
+  - Registered `audit` and `vitepress` commands in tool invocation mappings and decision gate options.
+
+---
+
+## [1.7.0] - 2026-09-09
+
+### 🚀 Added — Triple-Engine Publishing Platform (VitePress Integration) & Luxury RTL Design System
+- **VitePress Publishing Engine (references/commands/vitepress.md)**: Added full VitePress SSG engine support alongside MkDocs Material and Docsify.
+- **Ordered Workflow & Automation (references/workflows/vitepress.md)**: 6-step workflow covering scaffolding, multi-language subdirectory routing, luxury CSS injection, and zero-dead-link validation (npm run docs:build).
+- **Master Configuration & Luxury Tokens (references/memory/vitepress-config.md)**: Codified complete ESM config.mjs schema, Alexandria + Cairo + JetBrains Mono typography, surgical RTL navbar flex order, and Quick-Navigation grid templates.
+- **Luxury Hero & Actions Architecture**: Codified single-row CTA button flex safeguards (white-space: nowrap) and stable natural RTL Hero direction (Text/CTAs on right, Logo on left).
+- **3-Column Feature Cards & Column Collapse Fix**: Codified explicit width assignment on .VPFeatures .item and BiDi text safeguards.
+- **3-Way Engine Evaluation Matrix (references/memory/site-engines.md)**: Expanded to comprehensive 3-way evaluation across VitePress, MkDocs Material, and Docsify.
+
+---
+
+## [1.6.0] - 2026-09-08
+
+### 🧠 Added — Dual-Mode Decision Architect (DM-DA) & Debate Mode Engine (CDL v2.0)
+- **Interactive Interview & Debate Command (`brief`)**: Added `references/commands/brief.md` supporting trigger phrases `brief`, `interview`, `debate`, "استجوبني", and "ناقشني في معمارية التوثيق".
+- **Dual Operational Modes (`references/workflows/brief.md`)**:
+  - **[MODE A] Smart 3-Round Protocol**: Fast-track structured alignment in 3 deterministic rounds (Purpose & Target Persona ➔ Architecture & Engine ➔ Hygiene & Safe Defaults) terminating with an explicit escalation gate prompt.
+  - **[MODE B] Relentless Debate & Interview (Debate Mode)**: Deep multi-turn architectural counter-questioning, challenging assumptions on static vs. SPA, bilingual overhead, and automated secret scrubbing. Strictly terminates only on `"END DEBATE"` / `"اعتماد"`, emitting a formal `docs/architectural_debate_synthesis.md` artifact.
+- **Architectural Decision Matrix (`references/memory/decision-points.md`)**: Codified 5 core documentation dimensions (D1: Purpose & Scope, D2: Platform Engine, D3: Target Persona & Register, D4: Hygiene & Leak Policy, D5: Extraction Depth) with Boolean Skip Conditions for zero-overhead execution.
+- **Declarative Gate Expansion (`manifest.json`)**: Expanded manifest schema v1.1.0 with formal `brief` decision gates for D1–D5 with local YAML persistence (`.tidyfactor/doc-brief.snapshot.yaml`).
+
+---
+
+## [1.5.1] - 2026-09-08
+
+### 🏛️ Fixed & Synchronized — Governance Compliance (TidyFactor Skill Architect)
+- **Memory Freshness (Rule 11)**: Added `<!-- last-verified: 2026-09-08 -->` stamps to all stack memory files (`js-ts.md`, `php.md`, `react-vue-next.md`).
+- **Two-Tier Multi-Language Documentation (Rule 13)**:
+  - Integrated universal 8-language switcher bar into `README.md` and `README.ar.md`.
+  - Synchronized title banner versioning (`v1.5.1`) across all 8 market localizations (`README.md`, `README.ar.md`, `README.de.md`, `README.es.md`, `README.fa.md`, `README.fr.md`, `README.pt.md`, `README.zh.md`).
+- **Contextual Decision Layer CDL v2.0 (Rule 14)**:
+  - Integrated Step 0 Context Delta Resolution into `references/workflows/init-docs.md` with auto-sensing for `doc_engine`, `target_scope`, and `audience_persona`.
+- **Token Efficiency & YAML Primacy (Rule 15)**:
+  - Created canonical `brand.yaml` SSOT at skill root alongside `brand.json`.
+  - Updated `manifest.json` to persist decision snapshots to `.tidyfactor/doc-brief.snapshot.yaml` and discover from `brand.yaml`.
+
+---
+
+## [1.5.0] - 2026-09-02
+
+### 🧠 Added — Contextual Decision Layer (CDL v1.1.0) & Declarative Decision Gates
+- **Declarative Decision Gates (`manifest.json`)**: Added formal `decision_gates[]` declaration for the `init` command conforming to manifest schema v1.1.0, defining `doc_engine`, `target_scope`, and `audience_persona` with `track_staleness: true`.
+- **Context Delta Resolution Engine (`references/workflows/collect.md`)**: Upgraded collect workflow to evaluate the mechanical Delta formula:
+  $$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+- **Interactive Disclosure & User Agency First**: Surfacing all genuine Unknowns interactively with structured options and recommendations.
+- **Anti-Dual-Write Architecture**: Enforcing local markdown files under `docs/` as sole SSOT, with one-way outbound cloud sync via `--sync-brain`.
+
+---
+
+## [1.4.0] - 2026-09-02
+
+### 🧠 Added — Sovereign Brain MCP Integration, Hygiene Auditor & Fail-Open Protocol
+- **Brain Integration Contract (`references/memory/20-brain-baas-integration.md`)**: Sovereign self-hosted architecture and Documentation Knowledge Item (KI) payload schemas.
+- **Fail-Open Active Discovery (`references/workflows/collect.md`)**: Local workspace auto-sensing first, optional Brain MCP context acceleration (`search_knowledge_base`) when active, and instant 0ms silent fallback.
+- **Runtime Tooling Manifest (`manifest.json`)**: Declared portable `audit_docs` tool conforming to `skill-manifest.tools.schema.json` with `"skill_root_anchor": "self"`.
+- **Documentation Quality & Hygiene Auditor (`scripts/audit_docs.py`)**: Sub-second AST and pattern scanner detecting sensitive credentials leaks, passwords, private tokens, and banned absolute workstation URLs.
+- **Tooling Scope & Anti-Triggers**: Enriched `SKILL.md` with explicit Rule 10 Tooling Scope and anti-triggers.
 
 ---
 

package/README.ar.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# 📚 TidyFactor Doc `v1.3.0`
+# 📚 TidyFactor Doc `v1.9.0`
 ### محرك استقراء الأكواد البرمجية، وتوليد مراجع الـ API، ومنصة النشر المزدوجة (MkDocs Material و Docsify)
 
 **بناء توثيقات فنية دقيقة، مستدامة، آمنة، وقابلة للتصفح لعصر التعاون بين المطورين ووكلاء الذكاء الاصطناعي.**
@@ -12,7 +12,9 @@
 [![روابط نظيفة ونسبية](https://img.shields.io/badge/Links-Clean%20%26%20Relative-cyan.svg?style=for-the-badge)](#-معايير-الروابط-النسبية-والتصفح-النظيف)
 [![توافق شامل مع وكلاء الذكاء الاصطناعي](https://img.shields.io/badge/AI%20Agents-Universal%20Compatibility-4285F4.svg?style=for-the-badge)](README.md)
 
-[🌐 الموقع الرسمي](https://tidyfactor.com/) • [📚 مركز التوثيق](https://tidyfactor.com/documentation) • [🤝 الشريك (الوكالة)](https://alwkala.com/) • [⚡ سجل الأوامر](#-سجل-الأوامر-ومسارات-التوثيق-الأربعة) • [🛡️ الضمانات الأمنية](#-ضمانات-الأمان-وحجب-البيانات-الحساسة) • [📖 النسخة الإنجليزية (English)](README.md)
+[ English ](README.md) • [ العربية ](README.ar.md) • [ فارسی ](README.fa.md) • [ Español ](README.es.md) • [ Português ](README.pt.md) • [ 简体中文 ](README.zh.md) • [ Deutsch ](README.de.md) • [ Français ](README.fr.md)
+
+[🌐 الموقع الرسمي](https://tidyfactor.com/) • [📚 مركز التوثيق](https://tidyfactor.com/documentation) • [🤝 الشريك (الوكالة)](https://alwkala.com/) • [⚡ سجل الأوامر](#-سجل-الأوامر-ومسارات-التوثيق-الأربعة) • [🛡️ الضمانات الأمنية](#-ضمانات-الأمان-وحجب-البيانات-الحساسة)
 
 <br/><br/>
 
@@ -62,17 +64,24 @@ graph LR
 
 ---
 
-## 🏛️ سجل الأوامر ومسارات التوثيق الأربعة
+## 🏛️ سجل الأوامر ومسارات التوثيق الشاملة
 
 | نية المطور وطلب المستخدم | الأمر | مسارات العمل والذاكرة المحملة | المخرجات الناتجة |
 |---|---|---|---|
+| **"تأصيل سياق التوثيق، الاستجواب أو المناظرة المعمارية"** / "brief" / "debate" | `brief` | `workflows/brief.md`<br>`memory/decision-points.md` | وثيقة `.tidyfactor/doc-brief.snapshot.yaml` و `docs/architectural_debate_synthesis.md` |
 | **"تجهيز وهيكلة مجلد التوثيق"** / "scaffold /docs" | `init` | `workflows/init-docs.md`<br>`memory/doc-tree.md` | مجلد `/docs`، ملف `docs/.doc-manifest.json`، وصفحة `docs/README.md` |
 | **"استقراء وفحص الكود والمشروع"** / "gather facts" | `collect` | `workflows/collect.md`<br>`memory/collection-sources.md` | تقرير `docs/.collected/<target>.md` (تحليل منظم بالأبعاد الخمسة) |
 | **"كتابة مرجع واجهة برمجة (API)"** / "API reference" | `generate` | `workflows/generate-api.md`<br>`memory/doc-templates.md`<br>`memory/stacks/*.md` | ملف `docs/api/<target>.md` (جداول المعاملات، القيم المرجعة، الأخطاء) |
+| **"توليد أو تحديث سجل التغييرات"** / "generate changelog" | `generate` | `workflows/generate-changelog.md`<br>`memory/doc-templates.md`<br>`memory/changelog-rules.md` | ملف `CHANGELOG.md` في جذر المشروع (معيار Keep a Changelog و SemVer) |
 | **"كتابة دليل إعداد وتشغيل"** / "setup guide" | `generate` | `workflows/generate-guide.md`<br>`memory/doc-templates.md` | ملف `docs/guides/<purpose-slug>.md` (دليل متخصص محدد الغرض) |
 | **"توليد أو تحديث README الرئيسي"** / "generate readme" | `generate` | `workflows/generate-readme.md`<br>`memory/doc-templates.md` | ملف `README.md` في جذر المشروع (نظرة عامة، التثبيت، المتغيرات) |
 | **"إضافة تعليقات برمجية للكود"** / "inline docblocks" | `generate` | `workflows/generate-inline.md`<br>`memory/stacks/*.md` | تعديل مباشر للملفات المصدرية بتعليقات PHPDoc / JSDoc / TSDoc |
-| **"تحويل التوثيقات إلى موقع Docsify"** / "deploy portal" | `docsify` | `workflows/docsify.md`<br>`memory/docsify-config.md` | ملفات `docs/index.html` و`docs/_sidebar.md` (موقع تفاعلي متكامل) |
+| **"نشر بوابة توثيق متكاملة"** / "محدد تفاعلي" | `site` | `memory/site-engines.md` | اختيار تفاعلي بين (`vitepress` أو `mkdocs` أو `docsify`) |
+| **"إعداد بوابة VitePress الحديثة"** / "VitePress SSG" | `vitepress` | `workflows/vitepress.md`<br>`memory/vitepress-config.md` | ملفات `docs/.vitepress/config.mjs` وتنسيقات الـ RTL الفاخرة |
+| **"إعداد بوابة MkDocs Material"** / "Python SSG" | `mkdocs` | `workflows/mkdocs.md`<br>`memory/mkdocs-config.md` | ملف `mkdocs.yml` و `docs/stylesheets/extra.css` |
+| **"تحويل التوثيقات إلى موقع Docsify"** / "deploy portal" | `docsify` | `workflows/docsify.md`<br>`memory/docsify-config.md` | ملفات `docs/index.html` و`docs/_sidebar.md` (موقع تفاعلي فوري) |
+| **"تدقيق جودة الوثائق والروابط"** / "audit docs" | `audit` | `workflows/audit.md`<br>`scripts/audit_docs.py` | تقرير تدقيق AST آلي (فحص الروابط والبيانات الحساسة وسجل التغييرات) |
+| **"توثيق قرار معماري"** / "generate ADR" | `adr` | `workflows/generate-adr.md`<br>`memory/adr-template.md`<br>`memory/tone-of-voice.md` | ملف `docs/adr/NNNN-<slug>.md` وفهرس `docs/adr/README.md` |
 
 ---
 
@@ -129,13 +138,30 @@ project-root/
 
 ---
 
-## 🚀 التثبيت والتشغيل السريع
+## 🚀 التثبيت والبدء السريع
+
+اختر طريقة التثبيت المناسبة لمشروعك:
 
-### 1. تثبيت المهارة عبر NPM
-لإضافة مهارة `tidyfactor-doc` إلى مشروعك أو سجل الوكلاء لديك:
+### الخيار (أ): عبر TidyFactor CLI الرسمي (الموصى به)
+التثبيت الفوري دون الحاجة لتثبيت الأداة عالمياً في بيئة عملك النشطة:
+```bash
+npx @tidyfactor/cli add doc
+```
+*أو في حال كانت الأداة مثبتة لديك عالمياً (`npm i -g @tidyfactor/cli`):*
+```bash
+tidyfactor add doc
+```
+
+### الخيار (ب): عبر معيار مهارات الوكلاء المفتوح (skills.sh)
+التثبيت العالمي المتوافق مع كافة بيئات الوكلاء ومحررات الذكاء الاصطناعي (Antigravity, Cursor, Claude Code, Windsurf, Codex):
+```bash
+npx skills add tidyfactor/doc
+```
 
+### الخيار (ج): التثبيت المباشر الفردي عبر NPM
+تشغيل مثبت المهارة المستقل مباشرة مع تجاوز الذاكرة المخبأة وضمان أحدث إصدار:
 ```bash
-npx @tidyfactor/cli-doc add-skill
+npx @tidyfactor/doc@latest
 ```
 
 ### 2. التوافق الشامل مع وكلاء الذكاء الاصطناعي

package/README.de.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
 
 **Codebase Documentation Builder & Dual-Engine Publishing Platform (MkDocs & Docsify) für KI-Coding-Agenten**
 

package/README.es.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
 
 **Constructor de Documentación de Código y Motor de Publicación Dual (MkDocs & Docsify) para Agentes de IA**
 

package/README.fa.md

@@ -1,6 +1,6 @@
 <div align="center" dir="rtl">
 
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
 
 **موتور ساخت مستندات کد و انتشار دوگانه پورتال‌های مستندات (MkDocs و Docsify) برای ایجنت‌های هوش مصنوعی**
 

package/README.fr.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
 
 **Générateur de Documentation de Codebase et Plateforme de Publication Double (MkDocs & Docsify) pour Agents d'IA**
 

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
 
-# 📚 TidyFactor Doc `v1.3.0`
-### Automated Codebase Interview, API Generator & Dual-Engine Publishing Platform (MkDocs Material & Docsify)
+# 📚 TidyFactor Doc `v1.9.0`
+### Codebase Interview, API Generator, ADR Architect, Link Auditor & Triple-Engine Publishing Platform (VitePress, MkDocs Material & Docsify)
 
 **Building accurate, maintainable, secure, and browsable documentation for the era of Human-Agent Collaboration.**
 
@@ -13,7 +13,9 @@
 [![Universal AI Agents](https://img.shields.io/badge/AI%20Agents-Universal%20Compatibility-4285F4.svg?style=for-the-badge)](README.md)
 [![RTL Ready](https://img.shields.io/badge/RTL-Native%20Arabic-emerald.svg?style=for-the-badge)](README.ar.md)
 
-[🌐 Official Website](https://tidyfactor.com/) • [📚 Documentation](https://tidyfactor.com/documentation) • [🤝 Partner (Alwkala)](https://alwkala.com/) • [⚡ Commands](#-commands--the-4-phase-documentation-lifecycle) • [🛡️ Security Guarantees](#-enterprise-security--sanitization-guarantees) • [📖 Read in Arabic (بالعربية)](README.ar.md)
+[ English ](README.md) • [ العربية ](README.ar.md) • [ فارسی ](README.fa.md) • [ Español ](README.es.md) • [ Português ](README.pt.md) • [ 简体中文 ](README.zh.md) • [ Deutsch ](README.de.md) • [ Français ](README.fr.md)
+
+[🌐 Official Website](https://tidyfactor.com/) • [📚 Documentation](https://tidyfactor.com/documentation) • [🤝 Partner (Alwkala)](https://alwkala.com/) • [⚡ Commands](#-commands--the-4-phase-documentation-lifecycle) • [🛡️ Security Guarantees](#-enterprise-security--sanitization-guarantees)
 
 <br/><br/>
 
@@ -67,13 +69,20 @@ graph LR
 
 | Intent & User Request | Command | Loaded Workflow & Memory | Output Artifact |
 |---|---|---|---|
+| **"Establish doc context / interview / debate architecture"** / "brief" / "debate" | `brief` | `workflows/brief.md`<br>`memory/decision-points.md` | `.tidyfactor/doc-brief.snapshot.yaml`, `docs/architectural_debate_synthesis.md` |
 | **"Set up docs for this project"** / "scaffold /docs" | `init` | `workflows/init-docs.md`<br>`memory/doc-tree.md` | `/docs` scaffold, `docs/.doc-manifest.json`, `docs/README.md` |
 | **"Document this codebase"** / "gather facts for module X" | `collect` | `workflows/collect.md`<br>`memory/collection-sources.md` | `docs/.collected/<target>.md` (5-dimensional structured analysis) |
 | **"Write API reference"** / "generate docs for endpoints" | `generate` | `workflows/generate-api.md`<br>`memory/doc-templates.md`<br>`memory/stacks/*.md` | `docs/api/<target>.md` (parameter tables, returns, errors, examples) |
+| **"Generate CHANGELOG"** / "update release history" | `generate` | `workflows/generate-changelog.md`<br>`memory/doc-templates.md`<br>`memory/changelog-rules.md` | Root `CHANGELOG.md` (Keep a Changelog v1.1.0, SemVer 2.0.0) |
+| **"Record architectural decision"** / "generate ADR" | `adr` | `workflows/generate-adr.md`<br>`memory/adr-template.md`<br>`memory/tone-of-voice.md` | `docs/adr/NNNN-<slug>.md` & `docs/adr/README.md` index |
 | **"Write setup guide"** / "create architecture runbook" | `generate` | `workflows/generate-guide.md`<br>`memory/doc-templates.md` | `docs/guides/<purpose-slug>.md` (focused, single-purpose guide) |
 | **"Generate project README"** / "update root README" | `generate` | `workflows/generate-readme.md`<br>`memory/doc-templates.md` | Root `README.md` (overview, install, env vars, quick start) |
 | **"Add inline docblocks"** / "document public functions" | `generate` | `workflows/generate-inline.md`<br>`memory/stacks/*.md` | Direct source code edit with PHPDoc / JSDoc / TSDoc comments |
-| **"Turn /docs into Docsify site"** / "deploy doc portal" | `docsify` | `workflows/docsify.md`<br>`memory/docsify-config.md` | `docs/index.html` + `docs/_sidebar.md` (instant web portal) |
+| **"Publish documentation portal"** / "interactive selector" | `site` | `memory/site-engines.md` | Interactive selection (`vitepress`, `mkdocs`, `docsify`) |
+| **"Set up VitePress doc portal"** / "build Vue SSG" | `vitepress` | `workflows/vitepress.md`<br>`memory/vitepress-config.md` | `docs/.vitepress/config.mjs`, luxury RTL CSS |
+| **"Set up MkDocs Material"** / "compile static portal" | `mkdocs` | `workflows/mkdocs.md`<br>`memory/mkdocs-config.md` | `mkdocs.yml`, `docs/stylesheets/extra.css` |
+| **"Turn /docs into Docsify site"** / "deploy zero-build SPA" | `docsify` | `workflows/docsify.md`<br>`memory/docsify-config.md` | `docs/index.html` + `docs/_sidebar.md` (instant web portal) |
+| **"Audit doc quality / verify links & credentials"** / "audit" | `audit` | `workflows/audit.md`<br>`scripts/audit_docs.py` | AST quality report (link integrity, credential check, 100/100 score) |
 
 ---
 
@@ -147,13 +156,30 @@ project-root/
 
 ---
 
-## 🚀 Quick Start & Injection
+## 🚀 Installation & Quick Start
+
+Choose your preferred installation method:
 
-### 1. Inject Skill via NPM
-Add `tidyfactor-doc` to your active workspace or global agent registry:
+### Option A: Via TidyFactor CLI (Recommended)
+Install directly using the official ecosystem package runner into your active workspace:
+```bash
+npx @tidyfactor/cli add doc
+```
+*Or if you have the CLI installed globally (`npm i -g @tidyfactor/cli`):*
+```bash
+tidyfactor add doc
+```
+
+### Option B: Via Open Agent Skills Ecosystem (skills.sh / Vercel Labs)
+Install using the universal multi-agent standard across all supported IDEs (Cursor, Antigravity, Claude Code, Windsurf, Trae, Codex):
+```bash
+npx skills add tidyfactor/doc
+```
 
+### Option C: Standalone Zero-Dependency Runner (NPM Direct)
+Run the dedicated skill installer directly with automatic cache invalidation:
 ```bash
-npx @tidyfactor/cli-doc add-skill
+npx @tidyfactor/doc@latest
 ```
 
 ### 2. Universal Agent Compatibility

package/README.pt.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
 
 **Construtor de Documentação de Código e Motor de Publicação Duplo (MkDocs & Docsify) para Agentes de IA**
 

package/README.zh.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
 
 **面向 AI 智能体的代码库文档自动生成与双引擎发布平台 (MkDocs & Docsify)**
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tidyfactor-doc
-description: "Code documentation builder and dual-engine publishing platform (MkDocs Material and Docsify). Generates comprehensive API references, READMEs, inline docblocks, and technical guides under /docs. Trigger on commands 'init', 'collect', 'generate', 'site', 'mkdocs', 'docsify', or requests like 'document this codebase', 'generate API docs', 'set up MkDocs', or 'set up Docsify'."
+description: "Code documentation builder, ADR generator, and triple-engine publishing platform (VitePress, MkDocs Material, and Docsify). Generates API references, READMEs, changelogs, ADRs, inline docblocks, and guides. Trigger on commands 'brief', 'init', 'collect', 'generate', 'adr', 'site', 'vitepress', 'mkdocs', 'docsify', 'audit', or requests like 'document this codebase', 'generate ADR', 'create changelog', 'audit docs', or 'set up VitePress'."
 ---
 # TidyFactor Doc
 
@@ -10,12 +10,16 @@ A command dispatcher. This file does not do the work itself — it routes to the
 
 | User intent | Command | What it loads |
 |---|---|---|
+| "Establish documentation context / interview / debate codebase architecture" / "brief" / "debate" | `references/commands/brief.md` | `workflows/brief.md` + `memory/decision-points.md` |
 | "Set up docs for this project" / "scaffold /docs" | `references/commands/init.md` | `workflows/init-docs.md` + `memory/doc-tree.md` |
 | "Document this codebase" / "gather what's needed to document X" | `references/commands/collect.md` | `workflows/collect.md` + `memory/collection-sources.md` |
-| "Write API docs" / "generate a README" / "add inline comments" / "write a guide" | `references/commands/generate.md` | `workflows/generate-api.md` (or `generate-readme.md` / `generate-inline.md` / `generate-guide.md`) + `memory/doc-templates.md` + matching `memory/stacks/*.md` |
-| "Publish documentation portal" / "turn /docs into a doc site" (Interactive) | `references/commands/site.md` | `memory/site-engines.md` + interactive selection (`workflows/mkdocs.md` or `workflows/docsify.md`) |
+| "Record architectural decision / generate ADR" / "adr" | `references/commands/adr.md` | `workflows/generate-adr.md` + `memory/adr-template.md` + `memory/tone-of-voice.md` |
+| "Write API docs" / "generate a README" / "create CHANGELOG" / "add inline comments" / "write a guide" | `references/commands/generate.md` | `workflows/generate-api.md` (or `generate-readme.md` / `generate-changelog.md` / `generate-inline.md` / `generate-guide.md`) + `memory/doc-templates.md` + `memory/changelog-rules.md` + matching `memory/stacks/*.md` |
+| "Publish documentation portal" / "turn /docs into a doc site" (Interactive) | `references/commands/site.md` | `memory/site-engines.md` + interactive selection (`workflows/vitepress.md`, `workflows/mkdocs.md`, or `workflows/docsify.md`) |
+| "Set up VitePress" / "build modern Vue-powered doc portal" | `references/commands/vitepress.md` | `workflows/vitepress.md` + `memory/vitepress-config.md` |
 | "Set up MkDocs Material" / "compile static documentation" | `references/commands/mkdocs.md` | `workflows/mkdocs.md` + `memory/mkdocs-config.md` |
 | "Set up Docsify" / "build lightweight zero-build doc SPA" | `references/commands/docsify.md` | `workflows/docsify.md` + `memory/docsify-config.md` |
+| "Audit docs quality / scan credential leaks / verify links & changelog" / "audit" | `references/commands/audit.md` | `workflows/audit.md` + `scripts/audit_docs.py` |
 
 Read only the command file that matches the request. Do not read all commands simultaneously.
 
@@ -24,13 +28,32 @@ Read only the command file that matches the request. Do not read all commands si
 1. **All generated documentation lives under `/docs`.** Never write API references, guides, or generated READMEs to another location. (`README.md` itself stays at the project root, per convention — everything else generated goes in `/docs`.)
 2. **`generate` never invents content.** It only writes docs from what `collect` gathered (or equivalent detail the user supplies directly in the conversation) — never from assumed signatures, assumed env vars, or assumed behavior. If required detail is missing, `generate` says what's missing and asks or falls back to running `collect` first.
 3. **Stack rules are looked up, never guessed.** Before writing any code-level doc (API reference, inline comments), load the matching file under `memory/stacks/` for the language/framework actually in use. Do not mix PHPDoc conventions into a TypeScript file or vice versa.
-4. **`site`, `mkdocs`, and `docsify` only organize and publish what's already in `/docs`.** They never author new documentation content — that's `generate`'s job.
+4. **`site`, `vitepress`, `mkdocs`, and `docsify` only organize and publish what's already in `/docs`.** They never author new documentation content — that's `generate`'s job.
+   - For **VitePress**: Generate ESM `config.mjs`, inject luxury typography (`Alexandria` + `Cairo` + `JetBrains Mono`), enforce surgical RTL navbar order, single-row Hero action CTAs (`white-space: nowrap`), and explicit 3-column card widths (`width: 33.333333% !important`) with BiDi protection (`unicode-bidi: plaintext`). Build cleanly with `npx vitepress build docs`.
    - For **MkDocs Material**: Generate standard `mkdocs.yml`, configure Neo-Brutalist CSS tokens (`extra.css`), configure Arabic/English i18n (`*.ar.md` suffix), and build cleanly with `mkdocs build --strict`.
    - For **Docsify**: Include `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` and root-relative leading slashes `/` in `_sidebar.md` to guarantee persistent sidebar navigation across all subfolder routes.
 5. **Standalone.** This skill does not read or depend on any other `tidyfactor-*` skill's conventions, even when the project happens to be built on one of those tracks.
 6. **Zero Sensitive Data Leakage.** Under absolutely no circumstances should any real sensitive data (e.g., real API tokens, WHM/cPanel passwords, production server IPs, real DB credentials, secret keys, private auth tokens, or local absolute drive paths) be written into documentation. ALWAYS redact and replace these with safe generic placeholders.
 7. **Clean Relative Links Only.** Never include local machine filesystem URLs (such as `file:///C:/...`, `file:c:`, or absolute workstation paths) in documentation links or markdown cross-references. All document cross-links must use clean relative markdown paths or standard public web URLs (`https://...`).
 
+## Anti-Triggers
+
+- Do NOT use for writing marketing campaigns or sales copywriting (use `tidyfactor-marketing`).
+- Do NOT use for platform infrastructure management or deployment tasks (use `tidyfactor-github` or ops skills).
+
+## Tooling Scope (Rule 10)
+
+- **Execution Tools**:
+  - `audit_docs` (`scripts/audit_docs.py`): Sub-second AST scanner for documentation under `/docs`, root `README.md`, and `CHANGELOG.md`. Audits credential leaks, machine-specific paths, broken relative links, and Keep a Changelog formatting.
+  - `clean_orphaned_assets` (`scripts/clean_orphaned_assets.py`): Scans markdown documents for image references, detects unreferenced orphan assets in `assets/`, detects duplicate assets via SHA-256 hashing, and reports WebP compression opportunities.
+- **Contract & Schema**: Portably declared in `manifest.json` with `"skill_root_anchor": "self"`.
+- **Invocability**: Executable via direct CLI or through `tidyfactor-brain` MCP `run_skill_tool`.
+
+## Skill vs MCP Boundary (Rule 12)
+
+- **Inside Skill**: Static documentation templates, stack-specific docblock schemas, and local hygiene auditing scripts.
+- **MCP Layer**: Sovereign Brain persistence (`search_knowledge_base`, `extract_knowledge_item`) operating under the strict Fail-Open protocol (`references/memory/20-brain-baas-integration.md`).
+
 ## Sequencing
 
-`init` → `collect` → `generate` (repeatable, once per doc target) → `site` / `mkdocs` / `docsify` (optional, once /docs has real content).
+`brief` (optional, architectural alignment & debate) → `init` → `collect` → `adr` (record technical decisions) → `generate` (repeatable, once per doc target) → `site` / `vitepress` / `mkdocs` / `docsify` → `audit` (quality, links & orphan verification before release).

package/bin/add-skill.js

@@ -1,21 +1,42 @@
 #!/usr/bin/env node
+/**
+ * bin/add-skill.js — Multi-Agent Skill Installer Wrapper for tidyfactor-doc
+ * Supports Trae, Cursor, Windsurf, Antigravity, GitHub Copilot, RooCode, OpenCode, KiloCode, Warp, and Universal.
+ *
+ * @license Apache-2.0
+ */
+
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 const targetDir = process.cwd();
 const skillSource = path.resolve(__dirname, '..');
-const agentSkillsDir = path.join(targetDir, '.agents', 'skills', 'tidyfactor-doc');
+const skillName = 'tidyfactor-doc';
 
-fs.mkdirSync(agentSkillsDir, { recursive: true });
+const AGENT_MAP = [
+  { name: 'Trae AI IDE',               dir: path.join(targetDir, '.trae', 'skills', skillName),        test: path.join(targetDir, '.trae') },
+  { name: 'Cursor IDE',                dir: path.join(targetDir, '.cursor', 'skills', skillName),      test: path.join(targetDir, '.cursor') },
+  { name: 'Windsurf Cascade',          dir: path.join(targetDir, '.windsurf', 'skills', skillName),    test: path.join(targetDir, '.windsurf') },
+  { name: 'GitHub Copilot',            dir: path.join(targetDir, '.github', 'prompts', skillName),     test: path.join(targetDir, '.github') },
+  { name: 'RooCode',                   dir: path.join(targetDir, '.roo', 'skills', skillName),         test: path.join(targetDir, '.roo') },
+  { name: 'OpenCode / Zen',            dir: path.join(targetDir, '.opencode', 'skills', skillName),    test: path.join(targetDir, '.opencode') },
+  { name: 'KiloCode',                  dir: path.join(targetDir, '.kilocode', 'skills', skillName),    test: path.join(targetDir, '.kilocode') },
+  { name: 'Warp Terminal',             dir: path.join(targetDir, '.warp', 'skills', skillName),        test: path.join(targetDir, '.warp') },
+  { name: 'Kiro Spec IDE',             dir: path.join(targetDir, '.kiro', 'skills', skillName),        test: path.join(targetDir, '.kiro') },
+  { name: 'Claude Code',               dir: path.join(targetDir, '.claude', 'skills', skillName),      test: path.join(targetDir, '.claude') },
+  { name: 'Zed AI Agent',              dir: path.join(targetDir, '.zed', 'skills', skillName),         test: path.join(targetDir, '.zed') },
+  { name: 'Google Antigravity/Gemini', dir: path.join(targetDir, '.agents', 'skills', skillName),      test: path.join(targetDir, '.agents') },
+];
 
 function copyRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    if (['.git', 'node_modules', 'bin'].includes(entry.name)) continue;
+    if (['.git', 'node_modules', 'dist'].includes(entry.name)) continue;
     if (entry.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
       copyRecursive(srcPath, destPath);
     } else {
       fs.copyFileSync(srcPath, destPath);
@@ -23,5 +44,22 @@ function copyRecursive(src, dest) {
   }
 }
 
-copyRecursive(skillSource, agentSkillsDir);
-console.log('✓ Successfully injected tidyfactor-doc skill into .agents/skills/tidyfactor-doc');
+// Determine installation targets
+let mountedTargets = [];
+
+for (const agent of AGENT_MAP) {
+  if (fs.existsSync(agent.test)) {
+    copyRecursive(skillSource, agent.dir);
+    mountedTargets.push(agent.name + ' (' + path.relative(targetDir, agent.dir) + ')');
+  }
+}
+
+// Always ensure universal fallback in .agents/skills/
+const defaultDir = path.join(targetDir, '.agents', 'skills', skillName);
+copyRecursive(skillSource, defaultDir);
+if (!mountedTargets.some(t => t.includes('.agents'))) {
+  mountedTargets.push('Universal Default (.agents/skills/' + skillName + ')');
+}
+
+console.log('✨ Successfully injected ' + skillName + ' into:');
+mountedTargets.forEach(t => console.log('  • ' + t));

package/brand.json

@@ -1,6 +1,6 @@
 {
   "name": "TidyFactor Doc",
-  "version": "1.3.0",
+  "version": "1.9.0",
   "publisher": "TidyFactor Ecosystem",
   "partner": "Alwkala Digital Agency (https://alwkala.com)",
   "contact": {

package/brand.yaml

@@ -0,0 +1,10 @@
+name: "TidyFactor Doc"
+version: "1.9.0"
+publisher: "TidyFactor Ecosystem"
+partner: "Alwkala Digital Agency (https://alwkala.com)"
+contact:
+  website: "https://tidyfactor.com"
+  email: "hello@tidyfactor.com"
+  whatsapp: "+201016656899"
+  location: "Cairo, Egypt"
+license: "Apache-2.0"