diff --git a/README.ar.md b/README.ar.md index c82a45c..fecc7a8 100644 --- a/README.ar.md +++ b/README.ar.md @@ -129,13 +129,30 @@ project-root/ --- -## 🚀 التثبيت والتشغيل السريع +## 🚀 التثبيت والبدء السريع -### 1. تثبيت المهارة عبر NPM -لإضافة مهارة `tidyfactor-doc` إلى مشروعك أو سجل الوكلاء لديك: +اختر طريقة التثبيت المناسبة لمشروعك: +### الخيار (أ): عبر TidyFactor CLI الرسمي (الموصى به) +التثبيت الفوري دون الحاجة لتثبيت الأداة عالمياً في بيئة عملك النشطة: ```bash -npx @tidyfactor/cli-doc add-skill +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/doc@latest ``` ### 2. التوافق الشامل مع وكلاء الذكاء الاصطناعي diff --git a/README.md b/README.md index 8c26a08..43b2c55 100644 --- a/README.md +++ b/README.md @@ -147,13 +147,30 @@ project-root/ --- -## 🚀 Quick Start & Injection +## 🚀 Installation & Quick Start -### 1. Inject Skill via NPM -Add `tidyfactor-doc` to your active workspace or global agent registry: +Choose your preferred installation method: +### Option A: Via TidyFactor CLI (Recommended) +Install directly using the official ecosystem package runner into your active workspace: ```bash -npx @tidyfactor/cli-doc add-skill +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/doc@latest ``` ### 2. Universal Agent Compatibility diff --git a/dist/tidyfactor-doc-v1.1.0.skill b/dist/tidyfactor-doc-v1.1.0.skill deleted file mode 100644 index bb67d00..0000000 Binary files a/dist/tidyfactor-doc-v1.1.0.skill and /dev/null differ diff --git a/dist/tidyfactor-doc-v1.2.0.skill b/dist/tidyfactor-doc-v1.2.0.skill deleted file mode 100644 index e19e22a..0000000 Binary files a/dist/tidyfactor-doc-v1.2.0.skill and /dev/null differ diff --git a/dist/tidyfactor-doc-v1.2.1.skill b/dist/tidyfactor-doc-v1.2.1.skill deleted file mode 100644 index 45e304b..0000000 Binary files a/dist/tidyfactor-doc-v1.2.1.skill and /dev/null differ diff --git a/dist/tidyfactor-doc.skill b/dist/tidyfactor-doc.skill deleted file mode 100644 index aa8dbcf..0000000 Binary files a/dist/tidyfactor-doc.skill and /dev/null differ diff --git a/dist/tidyfactor-doc/.tidyfactor b/dist/tidyfactor-doc/.tidyfactor deleted file mode 100644 index 7b7e811..0000000 --- a/dist/tidyfactor-doc/.tidyfactor +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "tidyfactor-doc", - "version": "1.5.0", - "category": "development", - "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents", - "repository": "https://github.com/TidyFactor/Doc", - "npm": "@alwkala/tidyfactor-doc", - "compatibility": [ - "antigravity", - "claude-code", - "cursor", - "codex", - "windsurf" - ], - "license": "Apache-2.0" -} diff --git a/dist/tidyfactor-doc/AGENTS.md b/dist/tidyfactor-doc/AGENTS.md deleted file mode 100644 index 01ee9e5..0000000 --- a/dist/tidyfactor-doc/AGENTS.md +++ /dev/null @@ -1,10 +0,0 @@ -# AGENTS.md — TidyFactor Doc Governance Rules - -This file governs all AI coding agents working on or with `tidyfactor-doc`. - -## Core Invariants -1. **SSOT Rule:** `tidyfactor-doc/` in Skills-LAB is the single source of truth. -2. **Docs in `/docs` Only:** Generated documentation artifacts MUST live under `/docs` (except root `README.md`). -3. **No Assumed Details:** `generate` never invents facts or env vars not gathered during `collect`. -4. **Docsify Persistence:** Always generate `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` and root-relative paths. -5. **SemVer SSOT:** All changes must bump version and update `CHANGELOG.md`. diff --git a/dist/tidyfactor-doc/CHANGELOG.md b/dist/tidyfactor-doc/CHANGELOG.md deleted file mode 100644 index bdae747..0000000 --- a/dist/tidyfactor-doc/CHANGELOG.md +++ /dev/null @@ -1,89 +0,0 @@ -# CHANGELOG — TidyFactor Doc - -All notable changes to `tidyfactor-doc` will be documented in this file. -This project adheres to [Semantic Versioning](https://semver.org/). - -## [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. - ---- - -## [1.3.0] - 2026-08-29 - -### Added - Global Multi-Tier & Multi-Language Documentation Architecture -- **Rule 13 Implementation**: Two-tier documentation separation between Canonical Technical Documentation (`README.md` SSOT) and First-Class Market Localizations. -- **Universal Multi-Language Switcher**: Standardized 8-language switcher navigation bar across all documentation files (`EN`, `AR`, `FA`, `ES`, `PT`, `ZH`, `DE`, `FR`). -- **First-Class Localized Developer Adoption Guides**: `README.es.md`, `README.pt.md`, `README.fa.md`, `README.zh.md`, `README.de.md`, `README.fr.md`. -- **Automated Validation & Packaging**: Updated `tools/build-skill.js` and `tools/validate_skill.py`. - -## [1.2.0] - 2026-08-25 - -### Added -- **MkDocs Material Publishing Engine**: - - Full static HTML compilation track for high-performance production doc portals. - - Native bilingual parallel build support (`/` and `/ar/`) via `mkdocs-static-i18n`. - - Built-in Lunr.js offline search indexing (English + Arabic tokenization). - - Neo-Brutalist luxury styling tokens (`tidyfactor-light` & `tidyfactor-dark`) via `stylesheets/extra.css`. - - macOS-style terminal dots on highlighted code blocks with line spans. - - GitHub-style alert callout transformer (`[!IMPORTANT]`, `[!NOTE]`, `[!WARNING]`, `[!TIP]`) via `javascripts/extra.js`. - - Local Apache subfolder transparent routing via `.htaccess`. -- **Interactive Engine Selector Command (`site`)**: - - Interactive evaluation matrix in `references/commands/site.md` and `references/memory/site-engines.md`. - - Auto-detection of local Python/pip environment vs. zero-build CDN requirements. - - Clear user choice and recommendation guidance between MkDocs Material and Docsify. -- **Dedicated Direct Commands**: - - `mkdocs`: Direct entry point for MkDocs Material static portal compilation. - - `docsify`: Direct entry point for Docsify zero-build lightweight SPA. -- **New Workflows & Memory Specs**: - - `references/workflows/mkdocs.md`: End-to-end scaffolding, building, and validation checklist. - - `references/memory/mkdocs-config.md`: Master `mkdocs.yml` schema, theme configuration, and i18n rules. - - `references/memory/site-engines.md`: Technical comparison between Docsify and MkDocs Material. - ---- - -## [1.1.0] - 2026-08-20 - -### Added -- **Security Sanitization Constraint (Zero Sensitive Data Leakage)**: - - Enforced strict automated redaction of sensitive credentials across all workflows and memory files. - - Prohibited real API keys, passwords, database credentials, secret auth tokens, and private server IP addresses from leaking into `/docs`. - - Added safe placeholder standard replacements table in `references/memory/collection-sources.md` (RFC 5737 doc IP ranges, dummy token formats). -- **Clean Relative Links Constraint (Clean Relative Links Only)**: - - Prohibited local machine URLs (`file:///C:/...`, `file:c:`, and absolute workstation paths) in all generated documentation. - - Mandated clean relative markdown links (`./docs/README.md`, `../api/project.md`) and standard public URLs. -- **Workflow & Memory Hardening**: - - Updated `collect.md`, `generate-api.md`, `generate-guide.md`, `generate-readme.md`, `generate-inline.md`, and `docsify.md` with explicit validation checkboxes for zero credential leaks and clean link paths. - - Updated `doc-templates.md` to showcase secure dummy placeholders in environment variable tables and relative link cross-references. - - Added automated build pipeline script (`tools/build-skill.js`) for packaging and multi-target synchronization. - ---- - -## [1.0.0] - 2026-08-19 - -### Added -- Initial canonical release of `tidyfactor-doc` under the TidyFactor Skills-LAB ecosystem. -- Standard 4-command router architecture in `SKILL.md`: - - `init`: Scaffolds standard `/docs` folder structure and manifest. - - `collect`: Non-destructive codebase analysis for PHP, TS/JS, and React/Next stacks. - - `generate`: Produces API references, developer setup guides, inline docblocks, and READMEs. - - `docsify`: Generates responsive Docsify documentation websites with persistent subfolder sidebar routing. -- Stack-specific memory rules for PHP 8, TypeScript, JavaScript, and React/Vue/Next component docs. -- Full cross-agent compatibility across Google Antigravity, Claude Code, Cursor, Codex, and Windsurf. -- Packaging as `@tidyfactor/doc` under Apache License 2.0. diff --git a/dist/tidyfactor-doc/LICENSE b/dist/tidyfactor-doc/LICENSE deleted file mode 100644 index 8ea93e1..0000000 --- a/dist/tidyfactor-doc/LICENSE +++ /dev/null @@ -1,17 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - Copyright 2026 TidyFactor Ecosystem & Alwkala Digital Agency (https://alwkala.com) - - 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. diff --git a/dist/tidyfactor-doc/README.ar.md b/dist/tidyfactor-doc/README.ar.md deleted file mode 100644 index c82a45c..0000000 --- a/dist/tidyfactor-doc/README.ar.md +++ /dev/null @@ -1,180 +0,0 @@ -
- -# 📚 TidyFactor Doc `v1.3.0` -### محرك استقراء الأكواد البرمجية، وتوليد مراجع الـ API، ومنصة النشر المزدوجة (MkDocs Material و Docsify) - -**بناء توثيقات فنية دقيقة، مستدامة، آمنة، وقابلة للتصفح لعصر التعاون بين المطورين ووكلاء الذكاء الاصطناعي.** - -[![حزمة NPM](https://img.shields.io/npm/v/@tidyfactor/doc.svg?style=for-the-badge&color=4F46E5)](https://www.npmjs.com/package/@tidyfactor/doc) -[![الترخيص: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](LICENSE) -[![GitHub](https://img.shields.io/badge/GitHub-TidyFactor%2FDoc-181717.svg?style=for-the-badge&logo=github)](https://github.com/TidyFactor/Doc) -[![حماية البيانات والخصوصية](https://img.shields.io/badge/Security-Redaction%20Certified-emerald.svg?style=for-the-badge)](#-ضمانات-الأمان-وحجب-البيانات-الحساسة) -[![روابط نظيفة ونسبية](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) - -

- -

- TidyFactor Doc Hero Banner -

- -
- ---- - -> [!NOTE] -> **TidyFactor Doc** هو محرك حتمي لبناء التوثيقات الفنية ومواقع Docsify التفاعلية مخصص لوكلاء البرمجة الذكية (*Google Antigravity, Claude Code, Cursor, Codex, Windsurf*). يقوم باستقراء قواعد الأكواد والمشاريع البرمجية بدقة عبر فحص شجرة التعليمات البرمجية، وتاريخ التعديلات في Git، ومتغيرات بيئة التشغيل، وأنماط معالجة الأخطاء، لينتج مراكز توثيق متكاملة تحت مجلد `/docs` بدون أي تسريب للبيانات الحساسة أو روابط محلية معطوبة. - ---- - -## 🌟 القيمة المضافة ولماذا TidyFactor Doc؟ - -| للمطورين وقادة الفرق التقنية | لوكلاء البرمجة الذكية (AI Agents) | للمشاريع البرمجية والشركات | -|---|---|---| -| **انعدام الكتابة اليدوية**: استخراج تلقائي لمعمارية المشروع، وتواقيع الـ API، وخطوات التثبيت مباشرة من الكود المصدري. | **توجيه موفر للرموز (Tokens)**: موجه `SKILL.md` ذكي (~350 رمزاً) يحمّل مسار العمل وسياق الذاكرة المطلوب فقط. | **موقع Docsify فوري**: أمر واحد يحول مجلد `/docs` إلى بوابة توثيق ويب تفاعلية سريعة ومزودة بمحرك بحث فوري. | -| **منع تسريب البيانات السرية**: حجب وتنقيح تلقائي لمفاتيح API، وكلمات المرور، وبيانات قواعد البيانات، وعناوين IP. | **الاعتماد على الحقائق فقط**: منع اختلاق أي دوال أو معلمات غير موجودة؛ كل حقيقة موثقة مستندة لنتائج الفحص. | **دعم لغات متعددة (Polyglot)**: قوالب جاهزة لـ PHP 8+، وTypeScript، وJavaScript ES Modules، ومكونات React/Vue/Next. | -| **روابط نسبية نظيفة**: إزالة تامة لروابط `file:///` والمسارات المطلقة (`C:\...`) لضمان عمل التوثيق في أي بيئة. | **تحقق حتمي صارم**: كل مسار عمل يمتلك قائمة تدقيق وتتبع آلي للحالة في `docs/.doc-manifest.json`. | **دعم أصيل للغة العربية**: اتجاه RTL مدمج وتوافق طباعي فاخر (خطوط Cairo وTajawal مع Inter). | - ---- - -## 🔄 دورة حياة التوثيق ذات الـ 4 مراحل - -تتبع المهارة مساراً تسلسلياً حتمياً من 4 مراحل: - -```mermaid -graph LR - P1["1. التجهيز (Init)"] --> P2["2. الاستقراء (Collect)"] - P2 --> P3["3. التوليد (Generate)"] - P3 --> P4["4. النشر (Docsify)"] -``` - -``` -[ المرحلة 1: init ] ───> إنشاء هيكل مجلد /docs وملف التتبع .doc-manifest.json - │ -[ المرحلة 2: collect ] ─> استقراء الأبعاد الـ 5 (الكود، تاريخ Git، بيئة التشغيل، الجمهور، الأخطاء) وحفظها في docs/.collected/ - │ -[ المرحلة 3: generate ] ─> إنتاج مراجع API، الأدلة الفنية، التعليقات البرمجية، أو ملف README من الحقائق المستقرأة - │ -[ المرحلة 4: docsify ] ──> تجميع index.html و_sidebar.md للعرض المباشر في المتصفح والاستضافة الثابتة -``` - ---- - -## 🏛️ سجل الأوامر ومسارات التوثيق الأربعة - -| نية المطور وطلب المستخدم | الأمر | مسارات العمل والذاكرة المحملة | المخرجات الناتجة | -|---|---|---|---| -| **"تجهيز وهيكلة مجلد التوثيق"** / "scaffold /docs" | `init` | `workflows/init-docs.md`
`memory/doc-tree.md` | مجلد `/docs`، ملف `docs/.doc-manifest.json`، وصفحة `docs/README.md` | -| **"استقراء وفحص الكود والمشروع"** / "gather facts" | `collect` | `workflows/collect.md`
`memory/collection-sources.md` | تقرير `docs/.collected/.md` (تحليل منظم بالأبعاد الخمسة) | -| **"كتابة مرجع واجهة برمجة (API)"** / "API reference" | `generate` | `workflows/generate-api.md`
`memory/doc-templates.md`
`memory/stacks/*.md` | ملف `docs/api/.md` (جداول المعاملات، القيم المرجعة، الأخطاء) | -| **"كتابة دليل إعداد وتشغيل"** / "setup guide" | `generate` | `workflows/generate-guide.md`
`memory/doc-templates.md` | ملف `docs/guides/.md` (دليل متخصص محدد الغرض) | -| **"توليد أو تحديث README الرئيسي"** / "generate readme" | `generate` | `workflows/generate-readme.md`
`memory/doc-templates.md` | ملف `README.md` في جذر المشروع (نظرة عامة، التثبيت، المتغيرات) | -| **"إضافة تعليقات برمجية للكود"** / "inline docblocks" | `generate` | `workflows/generate-inline.md`
`memory/stacks/*.md` | تعديل مباشر للملفات المصدرية بتعليقات PHPDoc / JSDoc / TSDoc | -| **"تحويل التوثيقات إلى موقع Docsify"** / "deploy portal" | `docsify` | `workflows/docsify.md`
`memory/docsify-config.md` | ملفات `docs/index.html` و`docs/_sidebar.md` (موقع تفاعلي متكامل) | - ---- - -## 🛡️ ضمانات الأمان وحجب البيانات الحساسة - -أثناء تشغيل وكلاء الذكاء الاصطناعي، قد تتسرب مفاتيح سرية أو عناوين خوادم حقيقية إلى ملفات التوثيق العامة. تفرض `tidyfactor-doc` قواعد حجب صارمة وغير قابلة للتجاوز (**القاعدة الإلزامية 6**): - -| نوع البيانات الحساسة | المحظور منعه تماماً | البديل الآمن الإلزامي | -|---|---|---| -| **مفاتيح API والرموز السرية** | `sk_live_948f98a7c1b2...` | `EXAMPLE_TOKEN_1234567890ABCDEFGH` أو `YOUR_API_KEY` | -| **كلمات المرور وقواعد البيانات** | `RootP@ssw0rd2026!` | `your_secret_password` | -| **عناوين IP الخاصة بالخوادم** | `192.168.1.50`, `45.33.21.99` | `203.0.113.1` (نطاق RFC 5737 المخصص للتوثيق) | -| **روابط الملفات المحلية** | `file:///C:/path/to/project/...` | `./docs/guides/` أو `project-root/` | -| **روابط بيئة التطوير الداخلية** | `http://localhost:8080/admin` | `https://api.example.com` أو `http://localhost:PORT` | -| **مسارات مجلدات المستخدم** | `/home/developer/workspace/...` | `~/project` أو `/path/to/project` | - ---- - -## 🌐 معايير الروابط النسبية والتصفح النظيف - -لضمان عرض التوثيق بشكل سليم على GitHub، وGitLab، وDocsify، وبرامج قراءة الماركداون، تطبق المهارة **القاعدة الإلزامية 7**: - -- ❌ **منع المسارات المطلقة لمحطة العمل**: حظر تام لروابط `file:///` أو مسارات محركات الأقراص المحلية (`C:\...` أو `/Users/...`). -- ✅ **روابط نسبية نظيفة**: جميع الروابط الداخلية للمستندات تعتمد على المسارات النسبية القياسية (مثل `[دليل المعمارية](./guides/architecture.md)`). -- ✅ **توجيه مستقر ومستمر للقوائم في Docsify**: تكوين `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` مع شرطة مائلة جذرية `/` لمنع اختفاء القائمة الجانبية أو ظهور أخطاء 404 في المسارات المتداخلة. -- ✅ **صفحات التوثيق العربية داخل المجلد الرئيسي**: حفظ النسخ العربية داخل `/docs` مباشرة (مثل `docs/README.ar.md`) دون الربط بملفات خارجية خارج نطاق `/docs`. - ---- - -## 📁 الهيكل المعياري لمجلد `/docs` - -تلتزم جميع المشاريع المدارة بواسطة `tidyfactor-doc` بالهيكل النظيف الخالي من المجلدات الفارغة: - -``` -project-root/ -├── README.md # نظرة عامة والبدء السريع للمشروع (الجذر) -└── docs/ # مجلد التوثيق الموحد - ├── README.md # الصفحة الرئيسية لمركز التوثيق - ├── README.ar.md # النظرة العامة بالعربية - ├── index.html # بوابة Docsify التفاعلية - ├── _sidebar.md # شجرة التنقل والقائمة الجانبية المولدة آلياً - ├── .doc-manifest.json # ملف تتبع الحالة والمزامنة - ├── .collected/ # نتائج الاستقراء والفحص الأولي (ملف وسيط) - │ ├── core.md - │ └── auth-module.md - ├── api/ # مواصفات ومراجع واجهات البرمجة (API) - │ ├── authentication.md - │ └── billing.md - └── guides/ # الأدلة الفنية وأدلة المطورين والمستخدمين - ├── architecture.md - ├── developer-setup.md - └── deployment-runbook.md -``` - ---- - -## 🚀 التثبيت والتشغيل السريع - -### 1. تثبيت المهارة عبر NPM -لإضافة مهارة `tidyfactor-doc` إلى مشروعك أو سجل الوكلاء لديك: - -```bash -npx @tidyfactor/cli-doc add-skill -``` - -### 2. التوافق الشامل مع وكلاء الذكاء الاصطناعي -يمكنك استدعاء المهارة في بيئة التطوير المفضلة لديك: - -| الوكيل أو المحرر | مثال الاستدعاء | -|---|---| -| **Google Antigravity** | `/tidyfactor-doc` أو "وثق هذا المشروع وأنشئ موقع Docsify" | -| **Claude Code** | `/tidyfactor-doc init` أو "Generate API docs for src/Core" | -| **Cursor & Windsurf** | `@tidyfactor-doc جهز مجلد التوثيق وافحص مسار الكود` | -| **Codex CLI** | `tidyfactor-doc generate API reference` | - -### 3. المعاينة المحلية الفورية -لمعاينة موقع Docsify محلياً في المتصفح: - -```bash -# باستخدام خادم PHP المدمج -php -S localhost:3001 -t docs - -# أو باستخدام أداة Docsify CLI أو بايثون -npx docsify-cli serve docs -python -m http.server 3001 -d docs -``` - ---- - -## 👨‍💻 المنظمة والتواصل والدعم - -- 🌐 **الموقع الرسمي للمنظومة:** [https://tidyfactor.com/](https://tidyfactor.com/) -- 📚 **التوثيق الرسمي المعتمد:** [https://tidyfactor.com/documentation](https://tidyfactor.com/documentation) -- 🤝 **الشريك التقني الرسمي:** [وكالة الوكالة الرقمية Alwkala](https://alwkala.com/) -- 🐙 **منظمة GitHub الرسمية:** [github.com/TidyFactor](https://github.com/TidyFactor) -- 📧 **استفسارات الأعمال والشراكات:** [hello@tidyfactor.com](mailto:hello@tidyfactor.com) -- 📱 **واتساب:** [+20 101 665 6899](https://wa.me/201016656899) -- 📞 **الهاتف:** +20 101 665 6899 -- 📍 **المقر:** القاهرة، جمهورية مصر العربية - ---- - -## 📜 الترخيص والمجتمع - -مرخصة تحت رخصة **Apache License 2.0**. حقوق النشر محفوظة (c) 2026 لصالح [منظومة TidyFactor](https://tidyfactor.com) و[وكالة الوكالة الرقمية Alwkala](https://alwkala.com). diff --git a/dist/tidyfactor-doc/README.md b/dist/tidyfactor-doc/README.md deleted file mode 100644 index 8c26a08..0000000 --- a/dist/tidyfactor-doc/README.md +++ /dev/null @@ -1,198 +0,0 @@ -
- -# 📚 TidyFactor Doc `v1.3.0` -### Automated Codebase Interview, API Generator & Dual-Engine Publishing Platform (MkDocs Material & Docsify) - -**Building accurate, maintainable, secure, and browsable documentation for the era of Human-Agent Collaboration.** - -[![npm version](https://img.shields.io/npm/v/@tidyfactor/doc.svg?style=for-the-badge&color=4F46E5)](https://www.npmjs.com/package/@tidyfactor/doc) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](LICENSE) -[![GitHub](https://img.shields.io/badge/GitHub-TidyFactor%2FDoc-181717.svg?style=for-the-badge&logo=github)](https://github.com/TidyFactor/Doc) -[![Security Redaction Certified](https://img.shields.io/badge/Security-Redaction%20Certified-emerald.svg?style=for-the-badge)](#-enterprise-security--sanitization-guarantees) -[![Clean Links Verified](https://img.shields.io/badge/Links-Clean%20%26%20Relative-cyan.svg?style=for-the-badge)](#-clean-relative-links--navigation-standards) -[![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) - -

- -

- TidyFactor Doc Hero Banner -

- -
- ---- - -> [!NOTE] -> **TidyFactor Doc** is a deterministic documentation engine and Docsify architecture suite built for AI coding agents (*Google Antigravity, Claude Code, Cursor, Codex, Windsurf*). It systematically interviews a codebase—parsing source AST docblocks, Git commit rationale, runtime environment variables, and error patterns—to produce pristine, browsable `/docs` portals with zero manual drift, zero credential leaks, and zero broken local paths. - ---- - -## 🌟 Value Proposition & Why TidyFactor Doc? - -| For Developers & Tech Leads | For AI Coding Agents | For Open-Source & Enterprise | -|---|---|---| -| **Zero Manual Writing**: Non-destructive codebase analysis extracts architecture, API signatures, and setup flows directly from source. | **Token-Efficient Routing**: Router `SKILL.md` (~350 tokens) dispatches isolated workflows with exact memory context. | **Instant Docsify Portal**: One command transforms `/docs` into a responsive, searchable documentation website. | -| **Zero Sensitive Leakage**: Enforces automated redaction of API keys, passwords, database credentials, and production IPs. | **Fact-Grounded Only**: Agents are constrained from hallucinating signatures or parameters—everything traces to findings. | **Universal Polyglot**: Native templates for PHP 8+, TypeScript, JavaScript ES Modules, and React/Vue/Next components. | -| **Clean Relative Linking**: Eliminates broken `file:///` and machine paths (`C:\...`), guaranteeing portable markdown. | **Deterministic Validation**: Every workflow has an explicit checklist and manifest tracking in `docs/.doc-manifest.json`. | **Bilingual by Design**: Native LTR/RTL support with curated typography pairings (Inter + Cairo/Tajawal). | - ---- - -## 🔄 The 4-Phase Documentation Lifecycle - -`tidyfactor-doc` structures documentation generation into 4 sequential, deterministic phases: - -```mermaid -graph LR - P1["1. Init (Scaffold)"] --> P2["2. Collect (Interview)"] - P2 --> P3["3. Generate (Authoring)"] - P3 --> P4["4. Docsify (Publish)"] -``` - -``` -[ Phase 1: init ] ──> Creates /docs directory tree & .doc-manifest.json - │ -[ Phase 2: collect ] ─> Gathers 5 dimensions (Code AST, Git History, Env, Personas, Errors) into docs/.collected/ - │ -[ Phase 3: generate ] ─> Produces API refs, Guides, Inline comments, or Root README from collected facts - │ -[ Phase 4: docsify ] ─> Assembles index.html & _sidebar.md for instant static browser preview & hosting -``` - ---- - -## 🏛️ Commands & Workflows Registry - -| Intent & User Request | Command | Loaded Workflow & Memory | Output Artifact | -|---|---|---|---| -| **"Set up docs for this project"** / "scaffold /docs" | `init` | `workflows/init-docs.md`
`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`
`memory/collection-sources.md` | `docs/.collected/.md` (5-dimensional structured analysis) | -| **"Write API reference"** / "generate docs for endpoints" | `generate` | `workflows/generate-api.md`
`memory/doc-templates.md`
`memory/stacks/*.md` | `docs/api/.md` (parameter tables, returns, errors, examples) | -| **"Write setup guide"** / "create architecture runbook" | `generate` | `workflows/generate-guide.md`
`memory/doc-templates.md` | `docs/guides/.md` (focused, single-purpose guide) | -| **"Generate project README"** / "update root README" | `generate` | `workflows/generate-readme.md`
`memory/doc-templates.md` | Root `README.md` (overview, install, env vars, quick start) | -| **"Add inline docblocks"** / "document public functions" | `generate` | `workflows/generate-inline.md`
`memory/stacks/*.md` | Direct source code edit with PHPDoc / JSDoc / TSDoc comments | -| **"Turn /docs into Docsify site"** / "deploy doc portal" | `docsify` | `workflows/docsify.md`
`memory/docsify-config.md` | `docs/index.html` + `docs/_sidebar.md` (instant web portal) | - ---- - -## 🛡️ Enterprise Security & Sanitization Guarantees - -In modern AI agent workflows, sensitive credentials and private configurations frequently leak into documentation. `tidyfactor-doc` implements strict, non-negotiable redaction rules (**Constraint 6**): - -| Secret / Sensitive Category | Prohibited Leaks | Mandatory Safe Replacement | -|---|---|---| -| **API Tokens & Secret Keys** | `sk_live_948f98a7c1b2...` | `EXAMPLE_TOKEN_1234567890ABCDEFGH` or `YOUR_API_KEY` | -| **Passwords & DB Credentials** | `RootP@ssw0rd2026!` | `your_secret_password` | -| **Server & Host IPs** | `192.168.1.50`, `45.33.21.99` | `203.0.113.1` (RFC 5737 documentation prefix) | -| **Workstation File URIs** | `file:///C:/path/to/project/...` | `./docs/guides/` or `project-root/` | -| **Internal Development URLs** | `http://localhost:8080/admin` | `https://api.example.com` or `http://localhost:PORT` | -| **User Home Directories** | `/home/developer/workspace/...` | `~/project` or `/path/to/project` | - ---- - -## 🌐 Clean Relative Links & Navigation Standards - -To guarantee that documentation renders flawlessly on GitHub, GitLab, Docsify, and local markdown viewers, `tidyfactor-doc` enforces **Constraint 7**: - -- ❌ **Zero Absolute Drive Paths**: Never output `file:///` URLs or workstation drive letters (`C:\...`, `/Users/...`). -- ✅ **Clean Markdown Relative Links**: All internal document links use standard relative paths (e.g. `[Architecture Guide](./guides/architecture.md)`). -- ✅ **Docsify Persistent Subfolder Routing**: Configures `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` with root-relative leading slashes (`/guides/...`, `/api/...`) to eliminate 404 broken sidebars when navigating deep routes. -- ✅ **Localized Docs Inside Root**: Localized files reside inside `/docs` (e.g. `docs/README.ar.md`), never linking outside the `/docs` boundary. - ---- - -## 📁 Canonical `/docs` Folder Hierarchy - -Every project initialized and maintained by `tidyfactor-doc` strictly adheres to the flattened, no-empty-structures hierarchy: - -``` -project-root/ -├── README.md # Project overview & quick start (Root) -└── docs/ # Single documentation root - ├── README.md # Doc-site landing page & introduction - ├── README.ar.md # Arabic localized overview (optional) - ├── index.html # Docsify single-page application entry point - ├── _sidebar.md # Auto-generated categorized navigation tree - ├── .doc-manifest.json # Machine-readable sync & state manifest - ├── .collected/ # Raw interview findings (intermediate artifact) - │ ├── core.md - │ └── auth-module.md - ├── api/ # Public API & endpoint specifications - │ ├── authentication.md - │ └── billing.md - └── guides/ # Targeted developer & user guides - ├── architecture.md - ├── developer-setup.md - └── deployment-runbook.md -``` - -### `.doc-manifest.json` Schema -```json -{ - "project": "my-saas-platform", - "stacks": ["php", "ts", "react"], - "collected": { - "auth": "2026-08-20T14:30:00Z", - "core": "2026-08-20T14:32:00Z" - }, - "generated": { - "docs/api/auth.md": "2026-08-20T14:35:00Z", - "docs/guides/developer-setup.md": "2026-08-20T14:36:00Z", - "README.md": "2026-08-20T14:37:00Z" - } -} -``` - ---- - -## 🚀 Quick Start & Injection - -### 1. Inject Skill via NPM -Add `tidyfactor-doc` to your active workspace or global agent registry: - -```bash -npx @tidyfactor/cli-doc add-skill -``` - -### 2. Universal Agent Compatibility -Trigger the skill in your preferred AI Coding Assistant: - -| Agent / IDE | Invocation Example | -|---|---| -| **Google Antigravity** | `/tidyfactor-doc` or "Document this codebase and build a Docsify site" | -| **Claude Code** | `/tidyfactor-doc init` or "Generate API docs for src/Core" | -| **Cursor & Windsurf** | `@tidyfactor-doc Set up /docs and interview this PHP module` | -| **Codex CLI** | `tidyfactor-doc generate API reference` | - -### 3. Local Preview -Preview your Docsify documentation portal in real time: - -```bash -# Using PHP built-in server -php -S localhost:3001 -t docs - -# Or using Docsify CLI / Python -npx docsify-cli serve docs -python -m http.server 3001 -d docs -``` - ---- - -## 👨‍💻 Organization & Support - -- 🌐 **Official Website:** [https://tidyfactor.com/](https://tidyfactor.com/) -- 📚 **Official Documentation:** [https://tidyfactor.com/documentation](https://tidyfactor.com/documentation) -- 🤝 **Official Partner Website:** [Alwkala Digital Agency](https://alwkala.com/) -- 🐙 **GitHub Organization:** [github.com/TidyFactor](https://github.com/TidyFactor) -- 📧 **Business Inquiries:** [hello@tidyfactor.com](mailto:hello@tidyfactor.com) -- 📱 **WhatsApp:** [+20 101 665 6899](https://wa.me/201016656899) -- 📞 **Phone:** +20 101 665 6899 -- 📍 **Location:** Cairo, Egypt - ---- - -## 📜 License - -Licensed under the **Apache License 2.0**. Copyright (c) 2026 [TidyFactor](https://tidyfactor.com) & [Alwkala](https://alwkala.com). diff --git a/dist/tidyfactor-doc/SKILL.md b/dist/tidyfactor-doc/SKILL.md deleted file mode 100644 index 34f043e..0000000 --- a/dist/tidyfactor-doc/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -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'." ---- -# TidyFactor Doc - -A command dispatcher. This file does not do the work itself — it routes to the right command, which routes to the right workflow, which injects the right memory. - -## Commands - -| User intent | Command | What it loads | -|---|---|---| -| "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`) | -| "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` | - -Read only the command file that matches the request. Do not read all commands simultaneously. - -## Non-negotiable constraints on every command - -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. - - 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 & credential leak scanner for markdown docs under `/docs`. -- **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). diff --git a/dist/tidyfactor-doc/bin/add-skill.js b/dist/tidyfactor-doc/bin/add-skill.js deleted file mode 100644 index 551a203..0000000 --- a/dist/tidyfactor-doc/bin/add-skill.js +++ /dev/null @@ -1,65 +0,0 @@ -#!/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 skillName = 'tidyfactor-doc'; - -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', 'dist'].includes(entry.name)) continue; - if (entry.isDirectory()) { - copyRecursive(srcPath, destPath); - } else { - fs.copyFileSync(srcPath, destPath); - } - } -} - -// 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)); diff --git a/dist/tidyfactor-doc/brand.json b/dist/tidyfactor-doc/brand.json deleted file mode 100644 index b4e9b10..0000000 --- a/dist/tidyfactor-doc/brand.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "TidyFactor Doc", - "version": "1.5.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" -} diff --git a/dist/tidyfactor-doc/package.json b/dist/tidyfactor-doc/package.json deleted file mode 100644 index ab1df48..0000000 --- a/dist/tidyfactor-doc/package.json +++ /dev/null @@ -1,60 +0,0 @@ -{ - "name": "@tidyfactor/doc", - "version": "1.5.0", - "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents", - "main": "SKILL.md", - "bin": { - "tidyfactor-doc": "bin/add-skill.js", - "add-skill": "bin/add-skill.js", - "add-doc-skill": "bin/add-skill.js" - }, - "keywords": [ - "tidyfactor", - "docs", - "docsify", - "mkdocs", - "ai-agents", - "antigravity", - "claude-code", - "cursor", - "documentation-generator" - ], - "author": "TidyFactor (https://tidyfactor.com)", - "license": "Apache-2.0", - "repository": { - "type": "git", - "url": "git+https://github.com/TidyFactor/Doc.git" - }, - "scripts": { - "validate": "python tools/validate_skill.py", - "build": "node tools/build-skill.js", - "release": "python ../tools/release_skill.py ." - }, - "publishConfig": { - "access": "public" - }, - "files": [ - ".tidyfactor", - "AGENTS.md", - "CHANGELOG.md", - "LICENSE", - "README.ar.md", - "README.de.md", - "README.es.md", - "README.fa.md", - "README.fr.md", - "README.md", - "README.pt.md", - "README.zh.md", - "SKILL.md", - "assets", - "bin", - "brand.json", - "manifest.json", - "memory", - "references", - "scripts", - "templates", - "tools" - ] -} diff --git a/dist/tidyfactor-doc/references/commands/collect.md b/dist/tidyfactor-doc/references/commands/collect.md deleted file mode 100644 index 28b38cd..0000000 --- a/dist/tidyfactor-doc/references/commands/collect.md +++ /dev/null @@ -1,15 +0,0 @@ -# Command: collect - -Runtime entry point for "document this codebase" / "gather what's needed to document X." - -## Dispatch steps - -1. Load `../memory/collection-sources.md` — the five collection dimensions and what to extract from each. -2. Load `../workflows/collect.md` — the ordered interview/extraction sequence. -3. Run the workflow against the target codebase (or the specific slice of it the user named — a single module, endpoint, or component). - -## Does NOT - -- Does not write any files under `/docs`. `collect`'s output is structured source material (findings written to `docs/.collected/.md`, per `collect.md`'s own step) — not a finished doc. -- Does not load `memory/doc-templates.md` or any `memory/stacks/*.md` file — formatting the findings into a stack-correct doc is `generate`'s job, not this one. -- Does not require `init` to have run first, but if `docs/.doc-manifest.json` doesn't exist yet, say so and offer to run `init` first rather than silently creating an ad hoc structure. diff --git a/dist/tidyfactor-doc/references/commands/docsify.md b/dist/tidyfactor-doc/references/commands/docsify.md deleted file mode 100644 index e98fc7b..0000000 --- a/dist/tidyfactor-doc/references/commands/docsify.md +++ /dev/null @@ -1,15 +0,0 @@ -# Command: docsify - -Runtime entry point for "turn /docs into a doc site" / "set up Docsify (Zero-Build SPA)." - -## Dispatch steps - -1. Load `../memory/docsify-config.md` — file layout, plugin defaults, sidebar-generation rule, deploy targets. -2. Load `../workflows/docsify.md` — the setup sequence. -3. Confirm `/docs` already has real content (at least one generated doc beyond the scaffold). -4. Run `workflows/docsify.md`. - -## Does NOT - -- Does not author any new page content — it wires up navigation (`_sidebar.md`), an entry point (`index.html`), and optionally a cover page over whatever already exists in `/docs`. -- Does not load `memory/doc-templates.md` or any `memory/stacks/*.md` file. diff --git a/dist/tidyfactor-doc/references/commands/generate.md b/dist/tidyfactor-doc/references/commands/generate.md deleted file mode 100644 index f0a2c91..0000000 --- a/dist/tidyfactor-doc/references/commands/generate.md +++ /dev/null @@ -1,23 +0,0 @@ -# Command: generate - -Runtime entry point for "write API docs" / "generate a README" / "add inline comments" / "write a guide." A router within a router: figure out which doc type is wanted, then load exactly one workflow for it. - -## Dispatch steps - -1. **Identify the doc type.** If not obvious from the request, ask: - > "Which one — API reference, README, inline code comments, or a technical guide (setup/architecture/workflow)?" -2. **Identify the stack** (PHP / JS / TS / React / Vue / Next). If not obvious from the project, ask or detect from file extensions / config files (`composer.json`, `package.json` + `tsconfig.json`, framework config files). -3. Load the matching workflow — exactly one: - - API reference → `../workflows/generate-api.md` - - README → `../workflows/generate-readme.md` - - Inline comments → `../workflows/generate-inline.md` - - Guide → `../workflows/generate-guide.md` -4. Load `../memory/doc-templates.md`. -5. Load the matching stack file under `../memory/stacks/` — `php.md`, `js-ts.md`, or `react-vue-next.md`. Never load more than the stacks actually present in the target. -6. Confirm `collect` has already run for this target (check for `docs/.collected/.md`). If it hasn't, and the user hasn't supplied equivalent detail inline, stop and say so — do not generate from assumption. See constraint 2 in `SKILL.md`. -7. Run the loaded workflow. - -## Does NOT - -- Does not load more than one `workflows/generate-*.md` file per invocation. Multiple doc types requested at once → run this dispatch sequence once per type, sequentially. -- Does not load `memory/collection-sources.md` or `memory/docsify-config.md` — not this command's concern. diff --git a/dist/tidyfactor-doc/references/commands/init.md b/dist/tidyfactor-doc/references/commands/init.md deleted file mode 100644 index c407603..0000000 --- a/dist/tidyfactor-doc/references/commands/init.md +++ /dev/null @@ -1,15 +0,0 @@ -# Command: init - -Runtime entry point for "set up docs for this project" / "scaffold /docs." - -## Dispatch steps - -1. Load `../memory/doc-tree.md` — the canonical `/docs` folder shape and the doc-manifest schema. -2. Load `../workflows/init-docs.md` — the scaffolding sequence. -3. Run the workflow. - -## Does NOT - -- Does not write any actual documentation content (no API entries, no guide prose). That's `generate`. -- Does not run `collect`. If the user wants both, run `init` first, then hand off to `collect`. -- Does not load any `memory/stacks/*.md` file — stack detection here only decides which manifest fields to pre-fill, not how to document anything yet. diff --git a/dist/tidyfactor-doc/references/commands/mkdocs.md b/dist/tidyfactor-doc/references/commands/mkdocs.md deleted file mode 100644 index 30e7054..0000000 --- a/dist/tidyfactor-doc/references/commands/mkdocs.md +++ /dev/null @@ -1,15 +0,0 @@ -# Command: mkdocs - -Runtime entry point for "set up MkDocs" / "build MkDocs Material site" / "compile static documentation". - -## Dispatch steps - -1. Load `../memory/mkdocs-config.md` — master YAML schema, theme tokens, extensions, i18n rules, and deploy options. -2. Load `../workflows/mkdocs.md` — the setup and build sequence. -3. Confirm `/docs` has real content. -4. Run `workflows/mkdocs.md`. - -## Does NOT - -- Does not author new documentation content — it generates `mkdocs.yml`, configures themes, and compiles the static site. -- Does not modify source markdown semantics, only removes incompatible raw HTML wrappers. diff --git a/dist/tidyfactor-doc/references/commands/site.md b/dist/tidyfactor-doc/references/commands/site.md deleted file mode 100644 index 75c436d..0000000 --- a/dist/tidyfactor-doc/references/commands/site.md +++ /dev/null @@ -1,23 +0,0 @@ -# Command: site - -Runtime entry point for "turn /docs into a doc site" / "publish documentation portal" / "set up documentation site". - -## Dispatch steps - -1. Load `../memory/site-engines.md` — comparison between MkDocs Material and Docsify. -2. Confirm `/docs` has real content (at least one generated doc beyond the scaffold). -3. **Interactive Engine Selection:** - - Detect if Python is available via `python --version 2>&1`. - - If the user explicitly requested a specific engine (e.g., "use mkdocs" or "use docsify"), route directly: - - "mkdocs" → Dispatch `references/commands/mkdocs.md`. - - "docsify" → Dispatch `references/commands/docsify.md`. - - If no engine was specified: - - Present the two options to the user with the summary from `memory/site-engines.md`: - - **Option 1: MkDocs Material (Recommended for Production)**: Pre-compiled static HTML, 100/100 Core Web Vitals, bilingual (Arabic RTL + English LTR) parallel builds, offline search indexing, and Neo-Brutalist styling. Requires Python locally for building. - - **Option 2: Docsify (Zero-Build Lightweight SPA)**: Client-side SPA, zero build step, single `index.html` + `_sidebar.md` over CDN. Recommended when Python is not available or for internal repo prototyping. - - Prompt the user to pick their preference or proceed with the recommended engine based on detected toolchain. -4. Execute the chosen workflow (`workflows/mkdocs.md` or `workflows/docsify.md`). - -## Does NOT - -- Does not author any new markdown content — it structures, configures, and publishes what's already in `/docs`. diff --git a/dist/tidyfactor-doc/references/memory/collection-sources.md b/dist/tidyfactor-doc/references/memory/collection-sources.md deleted file mode 100644 index 883ecbd..0000000 --- a/dist/tidyfactor-doc/references/memory/collection-sources.md +++ /dev/null @@ -1,48 +0,0 @@ - -# Memory: collection-sources - -The five dimensions `collect` runs against a target, and exactly what to pull from each. Operational — no rationale. - -## 1. Code parsing - -- Extract existing docblocks/comments verbatim (don't paraphrase yet — that's `generate`'s job). -- List every public function, method, class, exported type, and (for components) prop/slot/event definition. -- Note which of these already have adequate comments vs. none vs. stale (comment doesn't match current signature). - -## 2. Commit history - -- `git log --follow -- ` for the target's files: pull commit messages that explain *why*, not routine messages ("fix typo"). -- Any available PR/MR descriptions touching the target: design decisions, rejected alternatives, known limitations mentioned by the author. -- Flag any TODO/FIXME/HACK comments found alongside — they're often undocumented known issues. - -## 3. Runtime & environment - -- Every environment variable the target reads (grep for `getenv`/`process.env`/`$_ENV`/config-loader calls), with whether it's required or optional and any default. -- Software dependencies and version constraints from the manifest (`composer.json`, `package.json`) that the target actually uses — not the whole project's dependency list. -- Any stated hardware/resource limits (memory limits, timeout values, rate limits) found in config or comments. -- **Sanitization Rule**: Never collect real values of secrets (API keys, passwords, JWT secrets, private IP addresses, database credentials). Store only the variable name, description, and a synthetic example placeholder (e.g. `sk_test_EXAMPLE123456`, `203.0.113.10`). - -## 4. User persona tracing - -- Classify the target's readership: **API consumer** (calls it from outside), **internal maintainer** (edits this code), **end-user** (uses a UI built on it), or a mix. -- For each persona present, note which facts from the other four dimensions matter to them — this list is what `generate` uses to prioritize content per doc type. - -## 5. Error patterns - -- Every thrown exception / returned error code / rejected promise in the target, with the condition that triggers it. -- How each error is meant to be handled or surfaced (caught and logged? bubbled to caller? shown to end-user?) — from code and any logging statements found. -- Common failure modes mentioned in commit history or TODO comments that aren't yet reflected in actual error handling. -- **Scrubbing Rule**: Redact real database connection strings, local absolute file paths (e.g. `/home/user/project/...`), or authorization headers that might appear in error logs or exception messages. - ---- - -## 🔒 Security & Link Sanitization Reference - -| Item Category | Dangerous / Prohibited | Mandatory Safe Replacement | -|---|---|---| -| API Keys / Tokens | `sk_live_948f98a7c...` | `YOUR_API_KEY_HERE` or `EXAMPLE_TOKEN_123` | -| Passwords / DB Secrets | `P@ssw0rd2026!` | `your_secure_password` | -| Server IPs | `192.168.1.15`, `45.33.21.99` | `203.0.113.1` (RFC 5737 doc range) | -| Local Drive Paths | `file:///C:/path/to/project/...` | `./docs/guides/` or `project-root/` | -| Local Workstation URLs | `http://localhost:8080/secret` | `https://api.example.com` or `http://localhost:PORT` | -| User Home Dirs | `/home/developer/workspace/...` | `~/project` or `/path/to/project` | diff --git a/dist/tidyfactor-doc/references/memory/doc-templates.md b/dist/tidyfactor-doc/references/memory/doc-templates.md deleted file mode 100644 index 8bb810d..0000000 --- a/dist/tidyfactor-doc/references/memory/doc-templates.md +++ /dev/null @@ -1,74 +0,0 @@ - -# Memory: doc-templates - -Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings. - -## API reference (`docs/api/.md`) - -```markdown -# API Reference - - - -## - - - -**Parameters** -| Name | Type | Required | Description | -|---|---|---|---| - -**Returns**: — - -**Throws / Errors**: - -**Example** - - ---- - - -## See also - -``` - -## README (project root `README.md`) - -```markdown -# - - - -## Requirements - - -## Setup - - -## Environment variables -| Variable | Required | Default | Description | Example | -|---|---|---|---|---| -| `API_KEY` | Yes | — | Secret authentication token | `EXAMPLE_TOKEN_1234567890ABCDEFGH` | -| `DB_HOST` | Yes | `localhost` | Database host IP or hostname | `203.0.113.10` | -| `DB_PASS` | Yes | — | Database user password | `your_secret_password` | - -## Usage - - -## Documentation -Full reference: [`/docs`](./docs/README.md) -``` - -## Guide (`docs/guides/.md`) - -```markdown -# - - - -##
- - -## Related - -``` diff --git a/dist/tidyfactor-doc/references/memory/doc-tree.md b/dist/tidyfactor-doc/references/memory/doc-tree.md deleted file mode 100644 index c26987c..0000000 --- a/dist/tidyfactor-doc/references/memory/doc-tree.md +++ /dev/null @@ -1,38 +0,0 @@ - -# Memory: doc-tree - -Canonical `/docs` folder shape and the manifest schema. Every command reads this before touching `/docs` so the structure stays identical across projects. - -## Folder shape - -``` -docs/ -├── README.md # doc-site landing page (generated by init) -├── .doc-manifest.json # tracking file (generated by init, updated by collect/generate) -├── .collected/ # raw findings from `collect`, one file per target — not site content -│ └── .md -├── api/ # one file per documented target — only if the project has an API surface -│ └── .md -└── guides/ # one file per guide purpose — only once at least one guide exists - └── .md -``` - -No Empty Structures: `init` creates `api/` only if the stack detection found an API surface (endpoints, public package exports), and `guides/` is created lazily by the first `generate-guide` run, not by `init`. `.collected/` is created lazily by the first `collect` run. - -## `.doc-manifest.json` schema - -```json -{ - "project": "", - "stacks": ["php" | "js" | "ts" | "react" | "vue" | "next", "..."], - "collected": { - "": "" - }, - "generated": { - "": "" - } -} -``` - -- `collected` and `generated` are separate: a target can be collected without anything generated from it yet. -- `generated` entries aren't limited to `/docs` paths — `generate-readme` writes to root `README.md` and `generate-inline` touches source files, both still tracked here for audit purposes. diff --git a/dist/tidyfactor-doc/references/memory/docsify-config.md b/dist/tidyfactor-doc/references/memory/docsify-config.md deleted file mode 100644 index e1dfcb7..0000000 --- a/dist/tidyfactor-doc/references/memory/docsify-config.md +++ /dev/null @@ -1,274 +0,0 @@ - -# Memory: docsify-config - -Fixed Docsify setup used by the `docsify` workflow. Not a menu of options — locked, production-tested config for TidyFactor documentation web portals. - -## `docs/index.html` Template - -```html - - - - - <PROJECT_NAME> Documentation - - - - - - -
- - - - - - - - - - -``` - -Replace `` from `docs/.doc-manifest.json`'s `project` field, and `` with project repository or developer link (`https://github.com/alwkala/TidyFactor-Go`). - ---- - -## Critical Rules & Lessons Learned - -### 1. Subfolder Navigation Sidebar Alias -- **CRITICAL**: Always configure `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` in `window.$docsify`. Without this alias, opening subfolder guides (e.g. `/#/guides/architecture-and-setup`) causes Docsify to look for `guides/_sidebar.md` and hide the sidebar menu! -- **CRITICAL**: Use leading slashes `/` for all links in `_sidebar.md` (`/guides/admin-user-guide.md`, `/api/project.md`) so links resolve relative to the `/docs` root from any route depth. - -### 2. Localized Pages Inside Docs Root -- **CRITICAL**: Docsify web root is `/docs`. Never link out of `/docs` using relative `../` paths (e.g. `../README.ar.md`), as Docsify SPA routing will throw `404 - Not Found`. -- Always place localized landing pages inside `/docs` (e.g. `docs/README.ar.md`), rendering smoothly at `/#/README.ar.md`. - -### 3. Hamburger Toggle Button (`.sidebar-toggle`) Styling -- Always style `.sidebar-toggle` and `.sidebar-toggle-button` with fixed positioning (`top: 14px; left: 14px; z-index: 1000`) and explicit `` lines (`width: 20px; height: 2px; display: block`) so the hamburger button remains accessible without collapsing or overlapping sidebar text items. - -### 4. Cross-Platform Emojis & Typography -- Country flag emojis (`🇸🇦`, `🇺🇸`) render as 2-letter codes (`SA`, `US`) on Windows Chrome/Edge. Use clean text badges (`[عربي]`, `[EN]`) in `_sidebar.md`. -- Always load Google Fonts (`Cairo` for Arabic RTL, `Inter` for English LTR, `Fira Code` for code blocks) in `docs/index.html`. - ---- - -## `_sidebar.md` Generation Rule - -Group by audience/purpose, root docs first, using leading slashes `/`: - -```markdown -- 🌐 [Overview / النظرة العامة](/README.md) -- 📖 [المقدمة بالعربية](/README.ar.md) -- 💡 [رؤية المنظومة والشركة](/guides/vision-and-ecosystem.md) - -- [عربي] أدلة المستخدم (User Guides - AR) - - [دليل مالك الموقع (Admin User Guide)](/guides/admin-user-guide.md) - - [دليل تحرير المحتوى (Editing Pages Content)](/guides/pages-editing-guide.md) - -- [EN] Developer & Technical Guides - - [Quick Start Guide](/guides/quick-start.md) - - [Platform & System Specifications](/guides/system-specifications.md) - - [AI Coding & Agent Workflows](/guides/ai-agent-workflows.md) - - [Content Engine Architecture & API](/guides/content-engine.md) - - [Architecture & Setup Guide](/guides/architecture-and-setup.md) - - [Database & Storage Architecture](/guides/database-and-storage.md) - - [Security & System Hardening](/guides/security-and-hardening.md) - - [Production Deployment & Hosting](/guides/deployment-and-hosting.md) - - [CMS Content Engine & Backups](/guides/cms-content-engine-and-backups.md) - -- 📚 REST API Reference - - [API Endpoints Specifications](/api/project.md) - ---- - -- 👨‍💻 Developed by [Alwkala](https://github.com/alwkala) -``` - -Regenerate the whole file each run so it never drifts from what's actually in `/docs`. - ---- - -## Preview - -Local static server: `php -S localhost:3001 -t docs` or `npx docsify-cli serve docs`. diff --git a/dist/tidyfactor-doc/references/memory/mkdocs-config.md b/dist/tidyfactor-doc/references/memory/mkdocs-config.md deleted file mode 100644 index 24f32ed..0000000 --- a/dist/tidyfactor-doc/references/memory/mkdocs-config.md +++ /dev/null @@ -1,171 +0,0 @@ - -# Memory: MkDocs Material Configuration Spec - -Complete architectural specification for scaffolding and compiling production-grade documentation portals with MkDocs Material. - ---- - -## 1. Package Requirements (`requirements.txt`) - -```text -mkdocs-material>=9.5 -mkdocs-static-i18n>=1.2 -``` - ---- - -## 2. Master Configuration Schema (`mkdocs.yml`) - -```yaml -site_name: Project Documentation -site_url: https://example.com/docs/ -site_description: "Production Documentation Portal" -site_author: Engineering Team - -docs_dir: docs -site_dir: site - -theme: - name: material - language: en - direction: ltr - custom_dir: overrides - - logo: assets/logo.png - favicon: assets/favicon.png - - font: - text: Plus Jakarta Sans - code: Fira Code - - palette: - # Light Mode - - media: "(prefers-color-scheme: light)" - scheme: tidyfactor-light - primary: custom - accent: custom - toggle: - icon: material/brightness-7 - name: Switch to Dark Mode - - # Dark Mode - - media: "(prefers-color-scheme: dark)" - scheme: tidyfactor-dark - primary: custom - accent: custom - toggle: - icon: material/brightness-4 - name: Switch to Light Mode - - features: - - navigation.tracking - - navigation.tabs - - navigation.tabs.sticky - - navigation.sections - - navigation.expand - - navigation.path - - navigation.top - - navigation.indexes - - navigation.footer - - search.suggest - - search.highlight - - search.share - - content.code.copy - - content.code.annotate - - content.tabs.link - - header.autohide - - toc.follow - -plugins: - - search: - separator: '[\s\-\.]+' - lang: - - en - - ar - - - i18n: - docs_structure: suffix - languages: - - locale: en - name: English - default: true - build: true - - locale: ar - name: العربية - build: true - theme: - language: ar - direction: rtl - font: - text: Tajawal - code: Fira Code - -markdown_extensions: - - abbr - - admonition - - attr_list - - def_list - - footnotes - - md_in_html - - tables - - toc: - permalink: true - toc_depth: 3 - - pymdownx.arithmatex: - generic: true - - pymdownx.betterem: - smart_enable: all - - pymdownx.caret - - pymdownx.details - - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg - - pymdownx.highlight: - anchor_linenums: true - line_spans: __span - pygments_lang_class: true - - pymdownx.inlinehilite - - pymdownx.keys - - pymdownx.mark - - pymdownx.smartsymbols - - pymdownx.superfences: - custom_fences: - - name: mermaid - class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format - - pymdownx.tabbed: - alternate_style: true - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tilde - -extra_css: - - stylesheets/extra.css - -extra_javascript: - - javascripts/extra.js -``` - ---- - -## 3. Bilingual Suffix Rule (i18n) - -- English source files: `docs/guides/architecture.md`, `docs/index.md` -- Arabic source files: `docs/guides/architecture.ar.md`, `docs/index.ar.md` -- Rule: Never link directly to `.ar.md` from `.md` files; the `i18n` plugin handles language linking automatically via the header switcher. - ---- - -## 4. Local Apache Subfolder Routing (`.htaccess`) - -When hosting the documentation inside a subfolder during local Apache/WAMP development: - -```apache - - RewriteEngine On - RewriteRule ^site(/.*)?$ - [L] - RewriteCond %{REQUEST_FILENAME} !-f - RewriteRule ^(.*)$ site/$1 [L] - -``` -In production: upload the contents of `site/` directly into `public_html/docs/`. diff --git a/dist/tidyfactor-doc/references/memory/site-engines.md b/dist/tidyfactor-doc/references/memory/site-engines.md deleted file mode 100644 index 96f24d0..0000000 --- a/dist/tidyfactor-doc/references/memory/site-engines.md +++ /dev/null @@ -1,55 +0,0 @@ - -# Memory: Site Engines (Docsify vs. MkDocs Material) - -Technical evaluation matrix for documentation publishing engines supported by `tidyfactor-doc`. - -## Engine Comparison Matrix - -| Capability / Factor | ⚡ MkDocs Material (Static Compiler) | 📄 Docsify (Client-Side SPA) | -|---|---|---| -| **Architecture** | Static Site Generator (Python Markdown) | Client-Side SPA (`marked.js` in browser) | -| **Output Type** | Pre-rendered static HTML (`site/`) | Single `index.html` fetching `.md` via AJAX | -| **Build Dependency** | Python 3.10+, `pip install mkdocs-material` | Zero build step, zero compiler required | -| **SEO & Crawlers** | 100/100 Perfect static HTML indexing | Limited (requires JS execution by bots) | -| **Performance & CWV** | Instant initial paint, pre-cached assets | Client-side fetch delay on slow mobile networks | -| **i18n & Localization** | Native parallel builds (`/` and `/ar/`) via `mkdocs-static-i18n` | Single page language or manual separate SPAs | -| **Search Engine** | Lunr.js pre-indexed offline search (bilingual) | In-browser client-side fuzzy search | -| **Styling & Theming** | Material for MkDocs + Neo-Brutalist CSS tokens | Custom CSS over Docsify default theme | -| **Code Highlighting** | Pygments build-time syntax highlighting + line spans | Prism.js client-side syntax highlighting | -| **Target Deployment** | Production doc portals, public SaaS products, multi-language sites | Rapid internal repo docs, single-file lightweight guides | - ---- - -## Decision Logic & Recommendation Rules - -1. **Choose MkDocs Material if:** - - The documentation has more than 10 pages or complex multi-level hierarchy. - - Public SEO visibility and search engine discoverability are critical. - - The project is bilingual (Arabic RTL + English LTR) requiring dedicated language switches. - - The local environment has Python installed (`python --version` returns 3.10+). - - Production hosting supports static directory routing (`public_html/documentation/`). - -2. **Choose Docsify if:** - - The developer or server environment has **no Python runtime** and requires zero installation. - - The project needs an instant browsable site by dropping a single `index.html` into `/docs`. - - The documentation is primarily for internal developers within a repository. - - The site is hosted on GitHub Pages with zero CI build workflows. - ---- - -## Two-Tier Multi-Language Documentation Pattern - -Both engines adhere to the TidyFactor Two-Tier Documentation standard: -- **Canonical Technical SSOT**: Full API specifications, architecture, and code deep-dives maintained in Canonical English (`/docs/en/` or root) with First-Class Arabic (`/docs/ar/`). -- **Localized Adoption Guides**: Quickstarts, tutorials, concepts, and command matrices for Tier 1/2 growth languages (`es`, `pt`, `fa`, `zh`, `de`, `fr`) providing high-conversion onboarding. - ---- - -## Toolchain Verification Command - -```bash -# Check if Python is available for MkDocs -python --version 2>&1 || python3 --version 2>&1 -``` -- If Python is available: recommend **MkDocs Material** as primary production track. -- If Python is not available: recommend **Docsify** as zero-dependency fallback. diff --git a/dist/tidyfactor-doc/references/memory/stacks/js-ts.md b/dist/tidyfactor-doc/references/memory/stacks/js-ts.md deleted file mode 100644 index 05461f2..0000000 --- a/dist/tidyfactor-doc/references/memory/stacks/js-ts.md +++ /dev/null @@ -1,45 +0,0 @@ -# Memory: stacks/js-ts - -Documentation conventions for JavaScript and TypeScript targets. Applies whenever the target's manifest is `package.json` and files are `.js`/`.mjs` (JS) or `.ts`/`.tsx` (TS). The two share JSDoc-style block syntax but differ in what needs restating. - -## JavaScript — JSDoc (types belong in the comment, since the code itself is untyped) - -```js -/** - * - * - * @param {string} name Description. - * @param {number} [limit] Optional, defaults to undefined. - * @returns {Promise} Description of the resolved shape. - * @throws {RangeError} When . - */ -``` - -- Always include `@param`/`@returns` types — JS has no compile-time types, so the comment is the only source of truth. -- Optional params use `[name]` bracket syntax. - -## TypeScript — TSDoc (types live in the signature, don't restate them in the comment) - -```ts -/** - * - * - * @param name - Description only, no type (already in the signature). - * @param limit - Description only. - * @returns Description only. - * @throws {RangeError} When . - */ -function example(name: string, limit?: number): Promise { ... } -``` - -- Do NOT restate types already visible in the TS signature (`{string}`, `{number}`) — that's a JSDoc habit that's redundant and can drift out of sync in TS. Description only after the `-`. -- Exported `interface`/`type` declarations get their own TSDoc block above the declaration, one line per member if the member itself isn't self-explanatory. - -## API reference formatting - -- Show the actual signature from the source (JS: as written; TS: full typed signature). -- For TS, prefer documenting the public exported types directly rather than re-describing them in prose. - -## What NOT to document inline - -- Non-exported (module-private) helper functions with obvious names: skip full blocks unless the error-patterns findings show them as a common failure point. diff --git a/dist/tidyfactor-doc/references/memory/stacks/php.md b/dist/tidyfactor-doc/references/memory/stacks/php.md deleted file mode 100644 index fd9f118..0000000 --- a/dist/tidyfactor-doc/references/memory/stacks/php.md +++ /dev/null @@ -1,33 +0,0 @@ -# Memory: stacks/php - -Documentation conventions for PHP targets. Applies whenever the target's manifest is `composer.json` or files are `.php`. - -## Inline comment format — PHPDoc - -```php -/** - * - * - * - * - * @param string $name Description of the parameter. - * @param int|null $limit Description. Optional, defaults to null. - * @return array Description of the return shape. - * @throws InvalidArgumentException When . - */ -``` - -- One blank-line-separated summary + description, then tags. -- Always type-hint `@param`/`@return` even when the function itself is already typed — PHPDoc types can be more specific (e.g. `array` vs. plain `array`). -- `@throws` is mandatory whenever the error-patterns findings show this function throwing — never omit it to save space. -- Class-level docblocks get `@package` only if the project already uses PSR-4 namespacing conventions that make it meaningful; skip otherwise. - -## API reference formatting - -- Signatures shown as the actual PHP declaration line (with type hints), not a paraphrase: `public function createUser(string $email, ?int $roleId = null): User` -- Nullable/union types shown exactly as declared (`?int`, `int|string`). -- Static vs. instance methods both documented the same way — note staticness in the signature itself, not as prose. - -## What NOT to document inline - -- Private/protected helper methods with obvious single-purpose names don't need a full docblock — a one-line `// ` comment is enough, or none if truly self-evident. Full PHPDoc blocks are for the public API surface. diff --git a/dist/tidyfactor-doc/references/memory/stacks/react-vue-next.md b/dist/tidyfactor-doc/references/memory/stacks/react-vue-next.md deleted file mode 100644 index 4dc9b1c..0000000 --- a/dist/tidyfactor-doc/references/memory/stacks/react-vue-next.md +++ /dev/null @@ -1,50 +0,0 @@ -# Memory: stacks/react-vue-next - -Component-level documentation conventions, layered on top of `js-ts.md` (still use JSDoc/TSDoc block syntax — this file adds what's specific to components, pages, and routes). - -## React — props, not just function signature - -```tsx -/** - * - */ -interface ButtonProps { - /** Description of this prop. */ - label: string; - /** Optional, defaults to 'primary'. */ - variant?: 'primary' | 'secondary'; - /** Called when clicked. */ - onClick?: () => void; -} -``` - -- Document props via the `interface`/`type` block (per-member comments), not a `@param` list on the component function — that's the idiomatic React pattern and what most tooling (Storybook, TypeDoc) expects. -- Note default values from the actual destructured defaults or `defaultProps`, not assumed. - -## Vue — SFC ` -``` - -- For Options API components (no `