@@ -62,17 +64,24 @@ graph LR --- -## 🏛️ سجل الأوامر ومسارات التوثيق الأربعة +## 🏛️ سجل الأوامر ومسارات التوثيق الشاملة | نية المطور وطلب المستخدم | الأمر | مسارات العمل والذاكرة المحملة | المخرجات الناتجة | |---|---|---|---| +| **"تأصيل سياق التوثيق، الاستجواب أو المناظرة المعمارية"** / "brief" / "debate" | `brief` | `workflows/brief.md`
`memory/decision-points.md` | وثيقة `.tidyfactor/doc-brief.snapshot.yaml` و `docs/architectural_debate_synthesis.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/
`memory/doc-templates.md`
`memory/stacks/*.md` | ملف `docs/api/
`memory/doc-templates.md`
`memory/changelog-rules.md` | ملف `CHANGELOG.md` في جذر المشروع (معيار Keep a Changelog و SemVer) | | **"كتابة دليل إعداد وتشغيل"** / "setup guide" | `generate` | `workflows/generate-guide.md`
`memory/doc-templates.md` | ملف `docs/guides/
`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` (موقع تفاعلي متكامل) | +| **"نشر بوابة توثيق متكاملة"** / "محدد تفاعلي" | `site` | `memory/site-engines.md` | اختيار تفاعلي بين (`vitepress` أو `mkdocs` أو `docsify`) | +| **"إعداد بوابة VitePress الحديثة"** / "VitePress SSG" | `vitepress` | `workflows/vitepress.md`
`memory/vitepress-config.md` | ملفات `docs/.vitepress/config.mjs` وتنسيقات الـ RTL الفاخرة | +| **"إعداد بوابة MkDocs Material"** / "Python SSG" | `mkdocs` | `workflows/mkdocs.md`
`memory/mkdocs-config.md` | ملف `mkdocs.yml` و `docs/stylesheets/extra.css` | +| **"تحويل التوثيقات إلى موقع Docsify"** / "deploy portal" | `docsify` | `workflows/docsify.md`
`memory/docsify-config.md` | ملفات `docs/index.html` و`docs/_sidebar.md` (موقع تفاعلي فوري) | +| **"تدقيق جودة الوثائق والروابط"** / "audit docs" | `audit` | `workflows/audit.md`
`scripts/audit_docs.py` | تقرير تدقيق AST آلي (فحص الروابط والبيانات الحساسة وسجل التغييرات) | +| **"توثيق قرار معماري"** / "generate ADR" | `adr` | `workflows/generate-adr.md`
`memory/adr-template.md`
`memory/tone-of-voice.md` | ملف `docs/adr/NNNN-
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
**Codebase Documentation Builder & Dual-Engine Publishing Platform (MkDocs & Docsify) für KI-Coding-Agenten**
diff --git a/README.es.md b/README.es.md
index b3f4eb9..29f1ae6 100644
--- a/README.es.md
+++ b/README.es.md
@@ -1,6 +1,6 @@
-# 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**
diff --git a/README.fa.md b/README.fa.md
index 589267f..e6aadf9 100644
--- a/README.fa.md
+++ b/README.fa.md
@@ -1,6 +1,6 @@
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
**موتور ساخت مستندات کد و انتشار دوگانه پورتالهای مستندات (MkDocs و Docsify) برای ایجنتهای هوش مصنوعی**
diff --git a/README.fr.md b/README.fr.md
index 465455b..179c522 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -1,6 +1,6 @@
-# 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**
diff --git a/README.md b/README.md
index 43b2c55..01ef508 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
-# 📚 TidyFactor Doc `v1.3.0`
-### Automated Codebase Interview, API Generator & Dual-Engine Publishing Platform (MkDocs Material & Docsify)
+# 📚 TidyFactor Doc `v1.10.0`
+### Codebase Interview, API Generator, ADR Architect, llms.txt Standard, 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 @@
[](README.md)
[](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)
@@ -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`
`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`
`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) |
+| **"Generate CHANGELOG"** / "update release history" | `generate` | `workflows/generate-changelog.md`
`memory/doc-templates.md`
`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`
`memory/adr-template.md`
`memory/tone-of-voice.md` | `docs/adr/NNNN-.md` & `docs/adr/README.md` index |
| **"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) | +| **"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`
`memory/vitepress-config.md` | `docs/.vitepress/config.mjs`, luxury RTL CSS | +| **"Set up MkDocs Material"** / "compile static portal" | `mkdocs` | `workflows/mkdocs.md`
`memory/mkdocs-config.md` | `mkdocs.yml`, `docs/stylesheets/extra.css` | +| **"Turn /docs into Docsify site"** / "deploy zero-build SPA" | `docsify` | `workflows/docsify.md`
`memory/docsify-config.md` | `docs/index.html` + `docs/_sidebar.md` (instant web portal) | +| **"Audit doc quality / verify links & credentials"** / "audit" | `audit` | `workflows/audit.md`
`scripts/audit_docs.py` | AST quality report (link integrity, credential check, 100/100 score) | --- diff --git a/README.pt.md b/README.pt.md index bdedd87..1265bd2 100644 --- a/README.pt.md +++ b/README.pt.md @@ -1,6 +1,6 @@
@@ -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`
`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`
`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/
`memory/doc-templates.md`
`memory/stacks/*.md` | `docs/api/
`memory/doc-templates.md`
`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`
`memory/adr-template.md`
`memory/tone-of-voice.md` | `docs/adr/NNNN-
`memory/doc-templates.md` | `docs/guides/
`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) | +| **"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`
`memory/vitepress-config.md` | `docs/.vitepress/config.mjs`, luxury RTL CSS | +| **"Set up MkDocs Material"** / "compile static portal" | `mkdocs` | `workflows/mkdocs.md`
`memory/mkdocs-config.md` | `mkdocs.yml`, `docs/stylesheets/extra.css` | +| **"Turn /docs into Docsify site"** / "deploy zero-build SPA" | `docsify` | `workflows/docsify.md`
`memory/docsify-config.md` | `docs/index.html` + `docs/_sidebar.md` (instant web portal) | +| **"Audit doc quality / verify links & credentials"** / "audit" | `audit` | `workflows/audit.md`
`scripts/audit_docs.py` | AST quality report (link integrity, credential check, 100/100 score) | --- diff --git a/README.pt.md b/README.pt.md index bdedd87..1265bd2 100644 --- a/README.pt.md +++ b/README.pt.md @@ -1,6 +1,6 @@
-# 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**
diff --git a/README.zh.md b/README.zh.md
index 25a3ca0..86574e7 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -1,6 +1,6 @@
-# tidyfactor-doc `v1.3.0`
+# tidyfactor-doc `v1.6.0`
**面向 AI 智能体的代码库文档自动生成与双引擎发布平台 (MkDocs & Docsify)**
diff --git a/SKILL.md b/SKILL.md
index 34f043e..ae6b556 100644
--- a/SKILL.md
+++ b/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, llms.txt standard generator, and triple-engine publishing platform (VitePress, MkDocs Material, and Docsify). Generates API references, READMEs, changelogs, ADRs, llms.txt, inline docblocks, and guides. Trigger on commands 'brief', 'init', 'collect', 'generate', 'adr', 'site', 'vitepress', 'mkdocs', 'docsify', 'audit', 'llms', or requests like 'document this codebase', 'generate ADR', 'create changelog', 'audit docs', 'generate llms.txt', or 'set up VitePress'."
---
# TidyFactor Doc
@@ -10,12 +10,17 @@ 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` |
+| "Generate llms.txt & llms-full.txt / AI agent documentation index" / "llms" | `references/commands/llms.md` | `workflows/generate-llmstxt.md` + `memory/llmstxt-spec.md` |
Read only the command file that matches the request. Do not read all commands simultaneously.
@@ -24,7 +29,8 @@ 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.
@@ -39,7 +45,8 @@ Read only the command file that matches the request. Do not read all commands si
## Tooling Scope (Rule 10)
- **Execution Tools**:
- - `audit_docs` (`scripts/audit_docs.py`): Sub-second AST & credential leak scanner for markdown docs under `/docs`.
+ - `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`.
@@ -50,4 +57,4 @@ Read only the command file that matches the request. Do not read all commands si
## 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` → `llms` (AI agent indexing) → `audit` (quality, links & orphan verification before release).
diff --git a/assets/og-default.png b/assets/og-default.png
deleted file mode 100644
index 1f4a843..0000000
Binary files a/assets/og-default.png and /dev/null differ
diff --git a/brand.json b/brand.json
index b4e9b10..95c5e60 100644
--- a/brand.json
+++ b/brand.json
@@ -1,6 +1,6 @@
{
"name": "TidyFactor Doc",
- "version": "1.5.0",
+ "version": "1.10.0",
"publisher": "TidyFactor Ecosystem",
"partner": "Alwkala Digital Agency (https://alwkala.com)",
"contact": {
diff --git a/brand.yaml b/brand.yaml
new file mode 100644
index 0000000..d69c18d
--- /dev/null
+++ b/brand.yaml
@@ -0,0 +1,10 @@
+name: "TidyFactor Doc"
+version: "1.10.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/manifest.json b/manifest.json
index 88057ae..28629db 100644
--- a/manifest.json
+++ b/manifest.json
@@ -5,7 +5,7 @@
"tools": [
{
"name": "audit_docs",
- "description": "Audits documentation files under /docs for sensitive data leaks, banned absolute URLs, relative link integrity, and Docsify/MkDocs compliance.",
+ "description": "Audits documentation files under /docs, root README.md, and CHANGELOG.md for sensitive data leaks, banned absolute URLs, relative link integrity, and Keep a Changelog compliance.",
"entrypoint": {
"runtime": "python3",
"script": "scripts/audit_docs.py"
@@ -38,22 +38,98 @@
"isolation_recommended": false,
"dependencies": []
},
- "invoked_by_commands": ["generate", "site", "mkdocs", "docsify", "audit"]
+ "invoked_by_commands": ["generate", "site", "vitepress", "mkdocs", "docsify", "audit", "adr", "llms"]
+ },
+ {
+ "name": "clean_orphaned_assets",
+ "description": "Scans markdown files for image references, identifies unreferenced orphan assets in assets/, detects duplicate assets via SHA-256 hashing, and evaluates WebP compression savings.",
+ "entrypoint": {
+ "runtime": "python3",
+ "script": "scripts/clean_orphaned_assets.py"
+ },
+ "invocation": {
+ "cli_pattern": "{runtime} {skill_root}/{script} {repo_root} {flags}",
+ "args": [
+ {
+ "name": "repo_root",
+ "type": "path",
+ "required": false,
+ "default": ".",
+ "description": "Root directory of repository or skill"
+ },
+ {
+ "name": "assets_dir",
+ "type": "string",
+ "required": false,
+ "default": "assets",
+ "flag": "--assets-dir",
+ "description": "Relative path to assets folder"
+ },
+ {
+ "name": "delete_orphans",
+ "type": "boolean",
+ "required": false,
+ "default": false,
+ "flag": "--delete-orphans",
+ "description": "Delete unreferenced assets on disk"
+ },
+ {
+ "name": "json",
+ "type": "boolean",
+ "required": false,
+ "default": false,
+ "flag": "--json",
+ "description": "Output pure JSON report"
+ }
+ ]
+ },
+ "output": {
+ "format": "json",
+ "channel": "stdout"
+ },
+ "runtime_requirements": {
+ "isolation_recommended": false,
+ "dependencies": []
+ },
+ "invoked_by_commands": ["audit", "site"]
}
],
"decision_gates": [
{
- "command": "init",
- "description": "Decision gate selecting documentation engine, navigation structure, and audience persona.",
+ "command": "brief",
+ "aliases": ["init", "debate"],
+ "description": "Decision gate selecting documentation engine, target persona, hygiene policy, and extraction scope.",
"decisions": [
{
- "key": "doc_engine",
- "description": "Target documentation publishing engine",
+ "key": "target_scope",
+ "description": "Scope of documentation generation (D1)",
"type": "enum",
- "options": ["mkdocs_material", "docsify_spa", "static_markdown"],
- "default": "mkdocs_material",
+ "options": ["full_codebase", "api_surface_only", "internal_architecture", "end_user_docs"],
+ "default": "full_codebase",
"priority": 1,
"discovery": [
+ {
+ "source": "local_file",
+ "path": "docs/.doc-manifest.json"
+ }
+ ],
+ "persist_to": {
+ "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
+ }
+ },
+ {
+ "key": "doc_engine",
+ "description": "Target documentation publishing engine (D2)",
+ "type": "enum",
+ "options": ["vitepress_ssg", "mkdocs_material", "docsify_spa", "static_markdown"],
+ "default": "vitepress_ssg",
+ "priority": 2,
+ "discovery": [
+ {
+ "source": "local_file",
+ "path": "docs/.vitepress/config.mjs",
+ "track_staleness": true
+ },
{
"source": "local_file",
"path": "mkdocs.yml",
@@ -70,7 +146,7 @@
}
],
"persist_to": {
- "local": { "path": ".tidyfactor/doc-brief.snapshot.json" },
+ "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" },
"brain_ki": {
"sync_direction": "outbound_push_only",
"requires_flag": "--sync-brain"
@@ -78,38 +154,60 @@
}
},
{
- "key": "target_scope",
- "description": "Scope of documentation generation",
+ "key": "audience_persona",
+ "description": "Primary audience reading the documentation (D3)",
"type": "enum",
- "options": ["full_codebase", "api_surface_only", "developer_guide", "end_user_docs"],
- "default": "full_codebase",
- "priority": 2,
+ "options": ["bilingual_developer", "api_consumer", "internal_maintainer", "end_user"],
+ "default": "bilingual_developer",
+ "priority": 3,
"discovery": [
{
"source": "local_file",
- "path": "docs/.doc-manifest.json"
+ "path": "brand.yaml",
+ "yaml_path": "audience"
+ },
+ {
+ "source": "local_file",
+ "path": "brand.json",
+ "json_path": "$.audience"
}
],
"persist_to": {
- "local": { "path": ".tidyfactor/doc-brief.snapshot.json" }
+ "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
}
},
{
- "key": "audience_persona",
- "description": "Primary audience reading the documentation",
+ "key": "hygiene_policy",
+ "description": "Security redaction and sensitive data leak policy (D4)",
"type": "enum",
- "options": ["api_consumer", "internal_maintainer", "end_user", "bilingual_developer"],
- "default": "bilingual_developer",
- "priority": 3,
+ "options": ["strict_zero_leak", "public_sdk_redaction", "internal_audit_permissive"],
+ "default": "strict_zero_leak",
+ "priority": 4,
+ "discovery": [
+ {
+ "source": "brain_ki",
+ "ki_type": "security"
+ }
+ ],
+ "persist_to": {
+ "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
+ }
+ },
+ {
+ "key": "collection_depth",
+ "description": "Extraction dimensions depth for codebase collection (D5)",
+ "type": "enum",
+ "options": ["full_5_dimensions", "signatures_and_types", "architecture_and_rationale"],
+ "default": "full_5_dimensions",
+ "priority": 5,
"discovery": [
{
"source": "local_file",
- "path": "brand.json",
- "json_path": "$.audience"
+ "path": "docs/.doc-manifest.json"
}
],
"persist_to": {
- "local": { "path": ".tidyfactor/doc-brief.snapshot.json" }
+ "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
}
}
]
diff --git a/package.json b/package.json
index ab1df48..6011186 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "@tidyfactor/doc",
- "version": "1.5.0",
- "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
+ "version": "1.10.0",
+ "description": "TidyFactor Doc — Code Documentation Builder, ADR Architect, llms.txt Standard Generator, Link Auditor & Triple-Engine Publishing Platform (VitePress, MkDocs Material & Docsify) for AI Coding Agents",
"main": "SKILL.md",
"bin": {
"tidyfactor-doc": "bin/add-skill.js",
@@ -50,6 +50,7 @@
"assets",
"bin",
"brand.json",
+ "brand.yaml",
"manifest.json",
"memory",
"references",
diff --git a/references/commands/adr.md b/references/commands/adr.md
new file mode 100644
index 0000000..2cafd2c
--- /dev/null
+++ b/references/commands/adr.md
@@ -0,0 +1,25 @@
+# Command: adr
+
+Runtime entry point for "Generate Architectural Decision Record (ADR)" / "وثق قرار معماري" / "قم بتوليد سجل قرار معماري يشرح سبب اختيار التقنية [X]".
+
+## Context-Aware Prompts & Auto-Sensing
+
+1. **Auto-Sense Project Context**:
+ - Inspect package manifests (`composer.json`, `package.json`, `go.mod`, `Cargo.toml`) and framework configs.
+ - Identify active language, runtime version, and primary dependencies.
+ - Check `docs/adr/` to discover existing records and determine the next sequence number (`NNNN`).
+
+2. **Extract Decision Parameters**:
+ - Technology / Decision subject: e.g. `[VitePress]`, `[Medoo ORM]`, `[SQLite Storage]`, `[TailAdmin]`.
+ - If not provided in the user prompt, evaluate recent commit history (`git log -n 10`) or prompt the user via the native modal question tool.
+
+3. **Dispatch to Workflow**:
+ - Load `../workflows/generate-adr.md` — the MADR decision-making workflow.
+ - Load `../memory/adr-template.md` — the authoritative Markdown ADR schema.
+ - Load `../memory/tone-of-voice.md` — technical objectivity and zero fluff policy.
+ - Run the workflow.
+
+## Does NOT
+
+- Does not guess technical justifications: facts must trace to actual codebase constraints, benchmarks, or requirements.
+- Does not edit application code: ADRs are purely architectural documentation saved under `docs/adr/`.
diff --git a/references/commands/audit.md b/references/commands/audit.md
new file mode 100644
index 0000000..ef23bca
--- /dev/null
+++ b/references/commands/audit.md
@@ -0,0 +1,15 @@
+# Command: audit
+
+Runtime entry point for "audit docs quality" / "scan documentation hygiene" / "check broken doc links" / "verify changelog structure."
+
+## Dispatch steps
+
+1. Identify the target path to audit (defaults to `docs/` and root `README.md`, `CHANGELOG.md` if not explicitly specified).
+2. Load `../workflows/audit.md` — the step-by-step documentation quality audit sequence.
+3. Run the workflow.
+
+## Does NOT
+
+- Does not rewrite or author documentation files automatically without user review.
+- Does not publish documentation sites (that's `site` / `mkdocs` / `docsify` / `vitepress`).
+- Does not modify code or package configurations.
diff --git a/references/commands/brief.md b/references/commands/brief.md
new file mode 100644
index 0000000..a969f44
--- /dev/null
+++ b/references/commands/brief.md
@@ -0,0 +1,16 @@
+# Command: brief
+
+Runtime entry point for establishing documentation context, running codebase interview, or conducting architectural debate ("brief", "interview", "debate", "استجوبني", "ناقشني في معمارية التوثيق").
+
+## Dispatch steps
+
+1. Load `../memory/decision-points.md` — the 5 core documentation decision dimensions (D1–D5), operational modes (Mode A / Mode B), and boolean skip conditions.
+2. Load `../workflows/brief.md` — the Context Delta Resolution, Dual Operational Mode execution, and persistence sequence.
+3. Run the workflow.
+
+## Does NOT
+
+- Does not author actual documentation content (no API entries, no guides, no READMEs). That's `generate`.
+- Does not scaffold `/docs` directory structure until baseline decisions are confirmed. That's `init`.
+- Does not run code-level AST parsing or git history log collection. That's `collect`.
+- Does not load `memory/stacks/*.md` or `memory/docsify-config.md` / `memory/mkdocs-config.md` — those are loaded only during generation or site compilation.
diff --git a/references/commands/generate.md b/references/commands/generate.md
index f0a2c91..4b1bde8 100644
--- a/references/commands/generate.md
+++ b/references/commands/generate.md
@@ -4,17 +4,18 @@ Runtime entry point for "write API docs" / "generate a README" / "add inline com
## 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).
+1. **Identify the doc type.** If not obvious from the request, ask or detect:
+ - API reference, README, CHANGELOG, 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). (Note: CHANGELOG and README are stack-agnostic).
3. Load the matching workflow — exactly one:
- API reference → `../workflows/generate-api.md`
- README → `../workflows/generate-readme.md`
+ - CHANGELOG → `../workflows/generate-changelog.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`.
+4. Load `../memory/doc-templates.md` (and `../memory/changelog-rules.md` if generating a CHANGELOG).
+5. Load the matching stack file under `../memory/stacks/` — `php.md`, `js-ts.md`, or `react-vue-next.md` (if stack-dependent). Never load more than the stacks actually present in the target.
+6. For code/API docs, confirm `collect` has already run for this target (check for `docs/.collected/.md`). For CHANGELOG, read git commit history (`git log`) and current `package.json` / version configs. If required detail is missing, stop and say so — do not generate from assumption. See constraint 2 in `SKILL.md`.
7. Run the loaded workflow.
## Does NOT
diff --git a/references/commands/llms.md b/references/commands/llms.md
new file mode 100644
index 0000000..b02d02b
--- /dev/null
+++ b/references/commands/llms.md
@@ -0,0 +1,28 @@
+# Command: llms
+
+Runtime entry point for generating and maintaining `/llms.txt` and `/llms-full.txt` files per the [llmstxt.org](https://llmstxt.org/) standard.
+
+---
+
+## Dispatch steps
+
+1. Load `../memory/llmstxt-spec.md` — Authoritative syntax rules (Single H1, blockquote summary, annotated link items).
+2. Load `../workflows/generate-llmstxt.md` — Crawling docs, building categorized index, concatenating full bundle, and wiring discovery links.
+3. Run the workflow.
+
+---
+
+## What It Does
+
+1. Inspects `/docs` and existing markdown files.
+2. Extracts concise summaries and logical hierarchy.
+3. Produces `docs/llms.txt` (lightweight index for AI model discovery).
+4. Produces `docs/llms-full.txt` (single concatenated markdown archive for context injection).
+5. Configures discovery `` headers for VitePress, MkDocs Material, or Docsify.
+
+---
+
+## Does NOT
+
+- Does not author brand-new documentation content from scratch (run `generate` first).
+- Does not inject binary or base64 assets into text files.
diff --git a/references/commands/site.md b/references/commands/site.md
index 75c436d..4b32b54 100644
--- a/references/commands/site.md
+++ b/references/commands/site.md
@@ -4,19 +4,21 @@ Runtime entry point for "turn /docs into a doc site" / "publish documentation po
## Dispatch steps
-1. Load `../memory/site-engines.md` — comparison between MkDocs Material and Docsify.
+1. Load `../memory/site-engines.md` — comparison between VitePress, 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:
+ - Detect available runtimes: `node --version 2>&1` and `python --version 2>&1`.
+ - If the user explicitly requested a specific engine (e.g., "use vitepress", "use mkdocs", or "use docsify"), route directly:
+ - "vitepress" → Dispatch `references/commands/vitepress.md`.
- "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.
+ - Present the options to the user with the summary from `memory/site-engines.md`:
+ - **Option 1: VitePress (Recommended for Modern Web, Monorepos & Luxury RTL)**: Vue 3 / Vite SSG, sub-second HMR, native multi-locale subdirectory routing (`/`, `/en/`, `/es/`), and bespoke luxury typography (`Alexandria` + `Cairo` + `JetBrains Mono`). Requires Node.js.
+ - **Option 2: MkDocs Material (Recommended for Python & Backend Services)**: Pre-compiled static HTML, 100/100 Core Web Vitals, parallel builds, offline search indexing, and Neo-Brutalist styling. Requires Python.
+ - **Option 3: Docsify (Zero-Build Lightweight SPA)**: Client-side SPA, zero build step, single `index.html` + `_sidebar.md` over CDN. Recommended when neither Node nor Python build workflows are available.
- 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`).
+4. Execute the chosen workflow (`workflows/vitepress.md`, `workflows/mkdocs.md`, or `workflows/docsify.md`).
## Does NOT
diff --git a/references/commands/vitepress.md b/references/commands/vitepress.md
new file mode 100644
index 0000000..ff909f7
--- /dev/null
+++ b/references/commands/vitepress.md
@@ -0,0 +1,20 @@
+# Command: vitepress
+
+Runtime entry point for "Set up VitePress" / "build modern Vue-powered doc portal" / "vitepress".
+
+## Dispatch steps
+
+1. Load `../memory/vitepress-config.md` — complete ESM configuration schema, luxury CSS custom tokens, and script presets.
+2. Confirm `/docs` has real content (at least one generated doc beyond the scaffold).
+3. Verify Node.js toolchain (`node --version` >= 18).
+4. Dispatch `../workflows/vitepress.md`.
+
+## Injects
+
+- `../workflows/vitepress.md`
+- `../memory/vitepress-config.md`
+
+## Does NOT
+
+- Does not author any new markdown content — it structures, configures, and publishes what's already in `/docs`.
+- Does not use external unverified CSS frameworks; relies strictly on custom luxury design tokens (`Alexandria` + `Cairo` + `JetBrains Mono` + RTL logical properties).
diff --git a/references/memory/adr-template.md b/references/memory/adr-template.md
new file mode 100644
index 0000000..1ae7b8c
--- /dev/null
+++ b/references/memory/adr-template.md
@@ -0,0 +1,84 @@
+
+# Memory: adr-template
+
+Authoritative MADR (Markdown Architectural Decision Records) schema for capturing significant architectural choices.
+
+## 1. Single Record Shape (`docs/adr/NNNN-.md`)
+
+```markdown
+# ADR [NNNN]: [Short Title of Solved Problem and Decision]
+
+- **Status**: [Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXXX]
+- **Date**: YYYY-MM-DD
+- **Decision-Makers**: [Architect / Agent / Team]
+- **Technical Story / Issue**: [Issue # or Feature Link]
+
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form or using 2-3 sentences. What forces are at play, what constraints must be satisfied?]
+
+## Decision Drivers
+
+- [Driver 1, e.g. sub-second build times]
+- [Driver 2, e.g. strict RTL and Arabic typography support]
+- [Driver 3, e.g. zero external runtime dependencies]
+
+## Considered Options
+
+- **Option 1**: [Name of Option 1]
+- **Option 2**: [Name of Option 2]
+- **Option 3**: [Name of Option 3]
+
+## Pros and Cons of the Options
+
+### Option 1: [Name]
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+
+### Option 2: [Name]
+
+- Good, because [argument a]
+- Bad, because [argument b]
+- Bad, because [argument c]
+
+## Decision Outcome
+
+**Chosen Option**: "[Option 1]", because [justification: e.g. it resolves Driver 1 and 2 while maintaining Driver 3].
+
+### Positive Consequences
+
+- [e.g. 80% reduction in asset footprint]
+- [e.g. Unified documentation deployment without Node.js runtime]
+
+### Negative Consequences / Trade-offs
+
+- [e.g. Requires manual markdown authoring instead of automated GUI]
+- [Mitigation: Automated pre-commit linting and link auditing]
+
+## Pros and Cons Matrix
+
+| Option | Performance | RTL Support | Maintenance Overhead | Ecosystem Maturity |
+|---|---|---|---|---|
+| Option 1 | High | Native | Low | High |
+| Option 2 | Medium | Partial | High | Very High |
+
+## References & Links
+
+- [Official Documentation](https://example.com)
+- [Related PR / Commit](https://github.com/org/repo/pull/1)
+```
+
+## 2. ADR Master Index Shape (`docs/adr/README.md`)
+
+```markdown
+# Architectural Decision Records (ADRs)
+
+This directory documents all significant architectural and technical decisions made in this project.
+
+| Number | Date | Title | Status |
+|---|---|---|---|
+| [0001](./0001-record-architecture-decisions.md) | 2026-09-09 | Record Architecture Decisions | Accepted |
+| [0002](./0002-triple-engine-publishing.md) | 2026-09-09 | Triple-Engine Publishing Platform | Accepted |
+```
diff --git a/references/memory/changelog-rules.md b/references/memory/changelog-rules.md
new file mode 100644
index 0000000..80d0829
--- /dev/null
+++ b/references/memory/changelog-rules.md
@@ -0,0 +1,58 @@
+
+# Memory: changelog-rules
+
+Codified rules and governance standards for maintaining `CHANGELOG.md` as the Single Source of Truth (SSOT) across all software and skill repositories.
+
+## 1. Authoritative Standards
+
+1. **Keep a Changelog v1.1.0**:
+ - Humans read changelogs, machines read git logs. Changelogs are curated summaries of user-facing and architectural value, not raw commit dumps.
+ - Guiding principles:
+ - Group changes by version and release date.
+ - Group changes within a release by type.
+ - Newest release always appears at the top (reverse chronological).
+ - Each version must have a release date formatted as `YYYY-MM-DD`.
+
+2. **Semantic Versioning (SemVer 2.0.0)**:
+ - Given a version number `MAJOR.MINOR.PATCH`:
+ - **`MAJOR` (x.0.0)**: Incompatible API changes, breaking architectural shifts, or removed features.
+ - **`MINOR` (0.x.0)**: Backward-compatible new functionality, new commands, or new workflows.
+ - **`PATCH` (0.0.x)**: Backward-compatible bug fixes, link repairs, or documentation corrections.
+
+## 2. Standard Change Sections
+
+Always classify changes into one of these 6 standardized buckets:
+
+| Section | Icon | Purpose |
+|---|---|---|
+| `Added` | 🚀 | New features, commands, workflows, or platform engines |
+| `Changed` | 🔄 | Modifications in existing functionality, refactors, or UI polish |
+| `Deprecated` | ⚠️ | Soon-to-be removed features that remain functional for now |
+| `Removed` | 🗑️ | Features, endpoints, or deprecated code deleted in this release |
+| `Fixed` | 🐛 | Any bug fixes, broken link repairs, or error corrections |
+| `Security` | 🔒 | Vulnerability fixes, credential redactions, or auth hardening |
+
+## 3. Conventional Commit Mapping
+
+When parsing `git log`, automatically map commit prefixes to changelog sections:
+
+| Git Commit Prefix | Changelog Section | SemVer Impact |
+|---|---|---|
+| `feat:` / `feat(*):` | `Added` | MINOR |
+| `refactor:` / `style:` / `perf:` | `Changed` | MINOR or PATCH |
+| `deprecate:` | `Deprecated` | MINOR |
+| `remove:` / `drop:` | `Removed` | MAJOR (if breaking) or MINOR |
+| `fix:` / `bug:` / `patch:` | `Fixed` | PATCH |
+| `sec:` / `security:` | `Security` | PATCH or MINOR |
+| `BREAKING CHANGE:` / `feat!:` | Any (`Added`/`Changed`) with breaking note | MAJOR |
+| `docs:` / `chore:` / `test:` | `Changed` or `Fixed` (or omitted if purely internal) | PATCH |
+
+## 4. Invariants & Hygiene
+
+- **Zero Undocumented Drift**: No production code or skill modification may be released without a corresponding dated entry in `CHANGELOG.md`.
+- **Atomic Metadata Synchronization**: When updating `CHANGELOG.md`, update all corresponding metadata files synchronously:
+ - `package.json` (`"version": "x.y.z"`)
+ - `.tidyfactor` (`"version": "x.y.z"`)
+ - `brand.yaml` / `brand.json` (`"version": "x.y.z"`)
+ - `README.md` / `README.ar.md` (Title banners)
+- **Zero Sensitive Data**: Never leak internal server paths, local absolute paths (`file:///C:`), or real API keys in changelogs.
diff --git a/references/memory/decision-points.md b/references/memory/decision-points.md
new file mode 100644
index 0000000..994db48
--- /dev/null
+++ b/references/memory/decision-points.md
@@ -0,0 +1,72 @@
+# Memory: decision-points
+
+
+
+Operational decision framework for documentation architecture and codebase interview governance. Enforces Contextual Decision Layer (CDL v2.0) and Dual-Mode Decision Architect (DM-DA) protocols.
+
+---
+
+## 🏛️ Decision Dimensions (D1–D5)
+
+| Code | Decision Dimension | Options (Reference SSOT) | Default Fallback | Ambiguity / Trigger Condition |
+|:---:|---|---|---|---|
+| **D1** | **Documentation Purpose & Scope** | • `full_codebase` (Complete API surface + architecture guides)
• `api_surface_only` (Public exports, routes, and client SDKs)
• `internal_architecture` (Developer onboarding, ADRs, module contracts)
• `end_user_docs` (User guides, tutorials, setup walkthroughs) | `full_codebase` | When request asks to "document this project" without specifying audience or depth. | +| **D2** | **Publishing Platform Engine** | • `mkdocs_material` (Static HTML compilation, lunr offline search, bilingual i18n)
• `docsify_spa` (Zero-build client runtime SPA, instant markdown preview)
• `static_markdown` (Raw markdown files under `/docs` with root README) | `mkdocs_material` (if python available) / `docsify_spa` | When user has not configured `mkdocs.yml` or `docs/index.html`. | +| **D3** | **Target Persona & Linguistic Register** | • `bilingual_developer` (Arabic/English parallel guides, technical terminology)
• `api_consumer` (Strict English technical docs, contract signatures)
• `internal_maintainer` (Architecture rationale, git commit history context)
• `end_user` (Simplified bilingual non-technical user documentation) | `bilingual_developer` | When project has not specified language or target reader in `brand.yaml`. | +| **D4** | **Hygiene & Redaction Policy** | • `strict_zero_leak` (Mandatory automated regex masking of all IPs, DB passwords, API tokens)
• `public_sdk_redaction` (Scrub all internal routes, mock endpoints only)
• `internal_audit_permissive` (Permit local loopback `127.0.0.1` and dummy sample envs) | `strict_zero_leak` | Mandatory for all public or open-source documentation generation. | +| **D5** | **Collection Depth & Extraction Dimensions** | • `full_5_dimensions` (Source AST + Git commit rationale + Env vars + Personas + Error patterns)
• `signatures_and_types` (Public function/class docblocks only)
• `architecture_and_rationale` (Module boundaries, ADRs, and commit history) | `full_5_dimensions` | Decides computational depth of subsequent `collect` workflow. | + +--- + +## 🧭 Dual Operational Modes (DM-DA) + +``` +[CDL v2.0 Protocol] + │ + ▼ + Context Delta Resolution ──(Unknowns = ∅)──► Instant Baseline Confirmation + │ + ├─► [MODE A] 🎯 Smart 3-Round Protocol (Deterministic alignment in 3 rounds) + │ Round 1: Purpose & Target Audience + │ Round 2: Engine & Architecture + │ Round 3: Boundaries, Hygiene & Safe Defaults + │ └── Escalation Gate: Confirm OR Escalate to Mode B + │ + └─► [MODE B] 🔥 Relentless Debate & Interview (Debate Mode) + Continuous multi-turn interrogation challenging assumptions + Forces binary trade-offs (static vs SPA, brevity vs depth) + Terminates strictly on: "END DEBATE" / "اعتماد" + Emits: architectural_debate_synthesis.md +``` + +### [MODE A] 🎯 Smart 3-Round Protocol (الارتجال الذكي المقيد) +- **Round 1: Purpose & Scope (D1 + D3)**: Pinpoint primary documentation consumer and technical scope. +- **Round 2: Architecture & Engine (D2 + D5)**: Select publishing engine and depth of code extraction. +- **Round 3: Hygiene & Safe Defaults (D4 + Remaining)**: Enforce security scrubbing rules and apply defaults. +- **Strict Termination**: Finishes at Round 3, saves snapshot, and presents the Escalation Gate: + > *"هل تعتمد هذه البنية المبدئية للبدء فوراً، أم تفضل تفعيل [نمط المناظرة 🔥 Debate Mode] لتفكيك الافتراضات واختبار صلابة الهيكلية التوثيقية؟"* + +### [MODE B] 🔥 Relentless Debate & Interview (الاستجواب والمناظرة اللانهائية — Debate Mode) +- **Activation**: Direct `/debate`, or Mode A Round 3 escalation. +- **Behavior**: + - Relentless multi-turn counter-questioning challenging documentation choices: + - *"Why choose Docsify client-side SPA if SEO and offline indexability are critical for external developers?"* + - *"Why document internal private methods if the primary goal is public API adoption?"* + - *"How will the team prevent confidential server IPs and auth secrets from slipping into generated guides?"* + - *"If the documentation is bilingual Arabic/English, how will code snippets and RTL UI callouts remain visually coherent without layout breakages?"* + - Exposes anti-patterns: bloated doc sets nobody reads, duplicate API references, undocumented environment configurations. + - Forces binary, uncompromising trade-offs. +- **Termination**: Ends **only** when user signals `"END DEBATE"` or `"اعتماد"`. +- **Deliverables**: + - Generates formal synthesis: `docs/architectural_debate_synthesis.md`. + - Persists confirmed parameters to `.tidyfactor/doc-brief.snapshot.yaml` and `.tidyfactor/doc-brief.md`. + +--- + +## ⚡ Boolean Skip Conditions (Deterministic Bypass) + +Skip interactive questioning and adopt safe defaults immediately if ANY condition is met: +1. **Existing Snapshot**: `.tidyfactor/doc-brief.snapshot.yaml` exists and `track_staleness` confirms zero file drift. +2. **Explicit User Declaration**: User specifies complete parameters in the prompt (e.g. *"Init MkDocs Material docs for public API with strict redaction"*). +3. **Direct Stack Command**: User calls specific engine commands directly (`/mkdocs` or `/docsify`). +4. **Maintenance Mode**: An audit (`audit_docs`) or validation run (`validate_skill.py`) preserves current configurations. diff --git a/references/memory/doc-templates.md b/references/memory/doc-templates.md index 8bb810d..50799a9 100644 --- a/references/memory/doc-templates.md +++ b/references/memory/doc-templates.md @@ -1,4 +1,4 @@ - + # Memory: doc-templates Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings. @@ -72,3 +72,31 @@ Full reference: [`/docs`](./docs/README.md) ## Related
```
+
+## CHANGELOG (project root `CHANGELOG.md`)
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### 🚀 Added
+-
+
+### 🐛 Fixed
+-
+
+## [1.0.0] - 2026-09-09
+
+### 🚀 Added
+- Initial production release.
+-
+
+---
+```
+
diff --git a/references/memory/git-doc-sync-hook.md b/references/memory/git-doc-sync-hook.md
new file mode 100644
index 0000000..222f73c
--- /dev/null
+++ b/references/memory/git-doc-sync-hook.md
@@ -0,0 +1,54 @@
+
+# Memory: git-doc-sync-hook
+
+Specification and configuration guide for pre-commit documentation synchronization hooks.
+
+## 1. Objective
+
+Prevent drift between code changes and documentation by verifying that when core functions, endpoints, or public APIs are modified in staged git commits, their corresponding documentation files in `/docs` or root `README.md` / `CHANGELOG.md` are also staged.
+
+## 2. Husky / Git Hook Implementation (`.husky/pre-commit` or `.git/hooks/pre-commit`)
+
+```bash
+#!/usr/bin/env bash
+# TidyFactor Doc Pre-Commit Guard
+set -e
+
+# 1. Check staged files
+STAGED_CODE=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(php|ts|js|py|go|rs)$' || true)
+STAGED_DOCS=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(^docs/|README\.md|CHANGELOG\.md)' || true)
+
+# 2. If core code changed, verify documentation activity or bypass flag
+if [ -n "$STAGED_CODE" ]; then
+ # Check if core services / interfaces were modified
+ CORE_CHANGES=$(echo "$STAGED_CODE" | grep -E '(Core/|Services/|Controllers/|api/|interfaces/)' || true)
+
+ if [ -n "$CORE_CHANGES" ] && [ -z "$STAGED_DOCS" ]; then
+ if [ "$DOC_OVERRIDE" != "1" ]; then
+ echo ""
+ echo "❌ [TidyFactor Doc Guard] Core code modified without documentation update!"
+ echo "Staged core files:"
+ echo "$CORE_CHANGES"
+ echo ""
+ echo "Please update corresponding files under /docs or CHANGELOG.md."
+ echo "To bypass intentionally for hotfixes, run: DOC_OVERRIDE=1 git commit -m '...'"
+ echo ""
+ exit 1
+ fi
+ fi
+fi
+
+# 3. Run audit_docs on staged docs
+if [ -n "$STAGED_DOCS" ]; then
+ echo "🔍 [TidyFactor Doc Guard] Auditing staged documentation quality..."
+ python scripts/audit_docs.py docs/
+fi
+
+exit 0
+```
+
+## 3. Benefits
+
+- Enforces the Single Source of Truth rule.
+- Eliminates stale documentation where APIs evolve but docs remain outdated.
+- Runs sub-second link and secret checks before commit creation.
diff --git a/references/memory/llmstxt-spec.md b/references/memory/llmstxt-spec.md
new file mode 100644
index 0000000..d98b2c4
--- /dev/null
+++ b/references/memory/llmstxt-spec.md
@@ -0,0 +1,95 @@
+# Memory: llmstxt-spec
+
+
+
+Technical specification and authoring standards for `/llms.txt` and `/llms-full.txt` files per the community standard ([llmstxt.org](https://llmstxt.org/)).
+
+---
+
+## 1. Overview & Purpose
+
+`llms.txt` is an advisory, machine-readable Markdown file placed at the project or documentation root (`/llms.txt` or `/docs/llms.txt`).
+It provides AI models, autonomous agents, and inference systems with a structured map of curated information, eliminating the need to crawl and parse bloated HTML structures.
+
+- **`/llms.txt`**: Fast, lightweight index containing the title, concise summary, and annotated markdown links to core sections.
+- **`/llms-full.txt`**: Consolidated bundle containing the complete, unabridged text of all documentation pages concatenated into a single plain-text markdown file.
+
+---
+
+## 2. File Format Specification (`/llms.txt`)
+
+Every `llms.txt` file must adhere strictly to the following syntax rules:
+
+### A. Single H1 Header (Mandatory)
+The file must start with exactly one `# H1` heading representing the project or library name:
+```markdown
+# Project Name
+```
+
+### B. Blockquote Summary (Mandatory)
+Immediately beneath the `# H1`, a blockquote (`> ...`) must describe the project, its core value proposition, tech stack, and audience in 1–3 concise sentences:
+```markdown
+> A lightweight modular architecture platform for building AI-agent-compatible web services and applications.
+```
+
+### C. H2 Categorized Sections
+Group documentation links into logical `## H2` categories (e.g., `## Core Concepts`, `## API Reference`, `## Guides`, `## Optional`):
+```markdown
+## Documentation
+
+- [Getting Started](https://example.com/docs/intro.md): Quickstart guide to install and configure the platform in under 5 minutes.
+- [Architecture](https://example.com/docs/architecture.md): Overview of Kernel contracts, Module interfaces, and dependency isolation.
+
+## API Reference
+
+- [Core API](https://example.com/docs/api/core.md): Detailed parameter and return type references for runtime controllers.
+```
+
+### D. Annotated Link Conventions
+- Format: `- [Link Title](url): Brief description of content and scope`.
+- All URLs should be canonical absolute URLs (or clean root-relative links if self-hosted within the repo).
+- Descriptions should explain *what* the document covers and *when* an LLM should retrieve it.
+
+---
+
+## 3. File Format Specification (`/llms-full.txt`)
+
+The consolidated version bundles the actual markdown content of all referenced docs:
+1. Starts with the exact same `# H1` and `> Summary` as `llms.txt`.
+2. Appends each documentation file separated by standard horizontal markdown dividers (`---`).
+3. Each section includes a reference header indicating its source route:
+ ```markdown
+ # Project Name
+ > Summary ...
+
+ ---
+
+ # Getting Started
+ Source: https://example.com/docs/intro.md
+
+ [Full Markdown content here...]
+
+ ---
+
+ # Architecture
+ Source: https://example.com/docs/architecture.md
+
+ [Full Markdown content here...]
+ ```
+
+---
+
+## 4. HTML Discovery Tags & Headers
+
+To ensure web crawlers and autonomous agents discover the `llms.txt` file without blind guessing, inject discovery links:
+
+### HTML `` tag:
+```html
+
+
+```
+
+### HTTP Response Header:
+```http
+Link: ; rel="describedby"; type="text/markdown"
+```
diff --git a/references/memory/naming-conventions.md b/references/memory/naming-conventions.md
new file mode 100644
index 0000000..feaca69
--- /dev/null
+++ b/references/memory/naming-conventions.md
@@ -0,0 +1,40 @@
+
+# Memory: naming-conventions
+
+Authoritative naming conventions across supported code stacks and documentation files.
+
+## 1. Documentation File System Conventions
+
+| Element | Format | Example | Anti-Pattern |
+|---|---|---|---|
+| Guide Slugs | `kebab-case.md` | `setup-guide.md` | `Setup_Guide.MD` |
+| ADR Records | `NNNN-kebab-case.md` | `0001-database-choice.md` | `1_db.md` |
+| Localized Guides | `[slug].[locale].md` | `architecture.ar.md` | `architecture_arabic.md` |
+| API References | `[component-or-class].md` | `user-service.md` | `UserServiceAPI.md` |
+| Internal Findings | `docs/.collected/[target].md` | `docs/.collected/auth.md` | `docs/.collected/Auth-Module.md` |
+
+## 2. Multi-Language Code Symbol Conventions
+
+### PHP (PSR-1 / PSR-12)
+- **Namespaces**: `PascalCase` (`App\Core\Registry`, `App\Modules\Blog`)
+- **Classes / Interfaces / Traits**: `PascalCase` (`AuthService`, `ModuleInterface`)
+- **Methods**: `camelCase` (`validateSession()`, `getUserById()`)
+- **Constants**: `UPPER_SNAKE_CASE` (`DEFAULT_TIMEOUT`, `MAX_RETRIES`)
+- **Variables / Properties**: `camelCase` (`$userId`, `$databaseConnection`)
+
+### TypeScript & JavaScript (ESM)
+- **Files & Modules**: `kebab-case.ts` (`auth-service.ts`) or `PascalCase.tsx` for React components (`UserProfile.tsx`)
+- **Types / Interfaces / Enums**: `PascalCase` (`UserSession`, `ApiResponse`, `LogLevel`)
+- **Functions / Methods**: `camelCase` (`parseManifest()`, `fetchUserData()`)
+- **Constants**: `UPPER_SNAKE_CASE` (`API_BASE_URL`, `TOKEN_EXPIRATION`)
+
+### Python (PEP 8)
+- **Modules / Packages**: `snake_case` (`audit_docs.py`, `clean_orphaned_assets.py`)
+- **Classes**: `PascalCase` (`DocumentationAuditor`, `MarkdownLinkScanner`)
+- **Functions / Methods**: `snake_case` (`scan_file()`, `check_relative_links()`)
+- **Constants**: `UPPER_SNAKE_CASE` (`SENSITIVE_PATTERNS`, `DEFAULT_SCORE`)
+
+## 3. REST API & Route Conventions
+
+- **Resource URIs**: Lowercase `kebab-case` plural nouns (`/api/v1/user-profiles`, `/api/v1/projects`).
+- **Query Parameters**: `snake_case` or `camelCase` (must be uniform per project, e.g. `page_size` or `pageSize`).
diff --git a/references/memory/project-mindmap.md b/references/memory/project-mindmap.md
new file mode 100644
index 0000000..8b98ea2
--- /dev/null
+++ b/references/memory/project-mindmap.md
@@ -0,0 +1,66 @@
+
+# Memory: project-mindmap
+
+Codified guidelines and Mermaid AST templates for generating clear, interactive architectural mind maps and component topology diagrams in documentation.
+
+## 1. Top-Level Architectural Layering (Mermaid C4 / Graph)
+
+```mermaid
+graph TD
+ Client["Client Layer (Browser / Agents)"]
+ Gateway["API & Router Layer"]
+ Core["Core Domain & Business Logic"]
+ Storage["Data Layer (SQLite / MySQL / Files)"]
+
+ Client -->|HTTP / JSON-RPC| Gateway
+ Gateway --> Core
+ Core --> Storage
+```
+
+## 2. Component Topology & Responsibility Mind Map
+
+```mermaid
+mindmap
+ root((System Architecture))
+ Presentation Layer
+ VitePress SSG
+ Docsify SPA
+ MkDocs Material
+ Core Logic
+ Command Dispatcher
+ Workflow Engine
+ Operational Memory
+ Execution Tooling
+ Link Integrity Auditor
+ AST Docblock Parser
+ Asset Hygiene Cleaner
+ Data & Context
+ Single Source of Truth
+ Brain Context Layer
+ Local File Snapshots
+```
+
+## 3. Data Flow & Execution Sequence Diagram
+
+```mermaid
+sequenceDiagram
+ autonumber
+ actor Dev as Developer / Agent
+ participant Dispatcher as SKILL.md Dispatcher
+ participant Workflow as Workflow Engine
+ participant Collector as Codebase Collector
+ participant Target as /docs Surface
+
+ Dev->>Dispatcher: Issue Command (brief / collect / generate)
+ Dispatcher->>Workflow: Load Matching Workflow & Memory
+ Workflow->>Collector: Scrape Signatures & Env Context
+ Collector-->>Workflow: Return 5-Dimension Findings
+ Workflow->>Target: Write Clean Markdown Artifacts
+ Workflow->>Dev: Emit Success Checklist & Audit Score
+```
+
+## 4. Usage Guidelines
+
+1. Place overarching mind maps in `docs/README.md` or `docs/guides/architecture.md`.
+2. Do not use raw image screenshots when Mermaid diagrams can represent topology directly in text.
+3. Keep node labels concise (≤ 4 words) to maintain high readability across mobile and desktop viewports.
diff --git a/references/memory/site-engines.md b/references/memory/site-engines.md
index 96f24d0..d22e303 100644
--- a/references/memory/site-engines.md
+++ b/references/memory/site-engines.md
@@ -1,55 +1,52 @@
-
-# Memory: Site Engines (Docsify vs. MkDocs Material)
+
+# Memory: Site Engines (VitePress vs. MkDocs Material vs. Docsify)
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 |
+| Capability / Factor | ⚡ VitePress (Vue 3 / Vite SSG) | 📦 MkDocs Material (Python Static) | 📄 Docsify (Client SPA) |
+|---|---|---|---|
+| **Architecture** | Static Site Generator (Vite + Vue 3 SSR) | Static Site Generator (Python Markdown) | Client-Side SPA (`marked.js`) |
+| **Output Type** | Pre-rendered static HTML (`dist/`) + Vue hydration | Pre-rendered static HTML (`site/`) | Single `index.html` fetching `.md` |
+| **Build Dependency** | Node.js >= 18, `npm i -D vitepress` | Python 3.10+, `pip install mkdocs-material` | Zero build step, zero compiler |
+| **SEO & Crawlers** | 100/100 Perfect static HTML indexing | 100/100 Perfect static HTML indexing | Limited (requires bot JS execution) |
+| **Performance & CWV** | Instant Vite dev server, sub-second HMR | High compilation speed, pre-cached assets | Client-side fetch delay on slow mobile |
+| **i18n & Localization** | Native subdirectory routing (`/`, `/en/`, `/es/`) | Parallel builds via `mkdocs-static-i18n` | Single language or manual SPAs |
+| **Search Engine** | Minisearch pre-indexed local search | Lunr.js pre-indexed offline search | In-browser client-side fuzzy search |
+| **Styling & Theming** | Custom CSS tokens, Vue components, Luxury RTL | Material theme + Neo-Brutalist tokens | Custom CSS over Docsify default |
+| **Code Highlighting** | Shiki build-time syntax highlighting | Pygments build-time syntax highlighting | Prism.js client-side syntax |
+| **Target Deployment** | Modern JS/TS repos, SaaS portals, luxury RTL | Python/Backend repos, enterprise wikis | Internal quick prototyping, single 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/`).
+1. **Choose VitePress if (Recommended for Modern Web / Monorepos):**
+ - The project is in the Node.js / TypeScript / Frontend ecosystem.
+ - Requires custom interactive Vue components, modern UI aesthetics, or luxury typography (`Alexandria` + `Cairo` + `JetBrains Mono`).
+ - Needs seamless multi-language subdirectory routing with zero 404s.
+ - Developer desires sub-second Vite HMR during drafting.
-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.
-
----
+2. **Choose MkDocs Material if:**
+ - The project is Python-centric or backend-heavy.
+ - The team is already using Python toolchains (`pip`, `virtualenv`).
+ - The documentation requires MkDocs-specific plugin ecosystems.
-## 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.
+3. **Choose Docsify if:**
+ - The developer environment has neither Node.js nor Python build workflows.
+ - The project needs an instant browsable site by dropping a single `index.html` into `/docs`.
+ - The documentation is strictly internal within a small Git repository.
---
## Toolchain Verification Command
```bash
-# Check if Python is available for MkDocs
+# Check available runtimes
+node --version 2>&1
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.
+- If Node.js is available: recommend **VitePress** as primary luxury web documentation portal.
+- If Python is available without Node.js: recommend **MkDocs Material**.
+- If no build runtime is available: recommend **Docsify** zero-dependency fallback.
diff --git a/references/memory/stacks/js-ts.md b/references/memory/stacks/js-ts.md
index 05461f2..4399235 100644
--- a/references/memory/stacks/js-ts.md
+++ b/references/memory/stacks/js-ts.md
@@ -1,5 +1,7 @@
# 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)
diff --git a/references/memory/stacks/php.md b/references/memory/stacks/php.md
index fd9f118..4d27c69 100644
--- a/references/memory/stacks/php.md
+++ b/references/memory/stacks/php.md
@@ -1,5 +1,7 @@
# 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
diff --git a/references/memory/stacks/react-vue-next.md b/references/memory/stacks/react-vue-next.md
index 4dc9b1c..786bcb1 100644
--- a/references/memory/stacks/react-vue-next.md
+++ b/references/memory/stacks/react-vue-next.md
@@ -1,5 +1,7 @@
# 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
diff --git a/references/memory/tone-of-voice.md b/references/memory/tone-of-voice.md
new file mode 100644
index 0000000..e7bf1b5
--- /dev/null
+++ b/references/memory/tone-of-voice.md
@@ -0,0 +1,31 @@
+
+# Memory: tone-of-voice
+
+Authoritative tone of voice and technical writing standards for all documentation produced by `tidyfactor-doc`.
+
+## 1. Core Principles
+
+1. **Direct & Action-Oriented**:
+ - Start sentences with verbs where possible: *"Install dependencies with `npm install`"*, not *"You may want to proceed by running npm install"*.
+ - Eliminate filler words: avoid *"clearly"*, *"obviously"*, *"simply"*, *"just"*, *"as you know"*.
+
+2. **Zero Marketing Fluff**:
+ - Technical documentation is not promotional copywriting.
+ - Do NOT use exaggerated marketing adjectives like *"revolutionary"*, *"best-in-class"*, *"magical"*, *"effortless"*.
+ - State engineering facts, constraints, and verifiable trade-offs objectively.
+
+3. **Semantic Density & Token Efficiency**:
+ - Use structured tables for parameters, configuration options, and error codes rather than paragraphs of running text.
+ - Favor short, concise bullet points (≤ 15 words) over dense narrative prose.
+
+4. **Clarity Over Cleverness**:
+ - Code examples must be minimal, self-contained, and working out of the box.
+ - Always document error cases and expected exceptions, not just happy paths.
+
+## 2. Bilingual English & Arabic Standards
+
+- **English**: Concise technical register (Imperative mood, active voice).
+- **Arabic**:
+ - Clear Modern Standard Arabic (فصحى معاصرة رصينة ومباشرة).
+ - Use established technical terminology (e.g. "التوثيق البرمجي", "نقاط النهاية API", "سجل القرارات المعمارية ADR", "المزامنة الذرية").
+ - Preserve English code symbols and keyword references within markdown inline code blocks (`code`).
diff --git a/references/memory/vitepress-config.md b/references/memory/vitepress-config.md
new file mode 100644
index 0000000..a543d79
--- /dev/null
+++ b/references/memory/vitepress-config.md
@@ -0,0 +1,174 @@
+
+# Memory: VitePress Configuration Spec & Luxury Theme Architecture
+
+Complete architectural specification for scaffolding, configuring, and styling production-grade documentation portals with VitePress, luxury typography, and full RTL layout parity.
+
+---
+
+## 1. Master ESM Configuration Schema (`docs/.vitepress/config.mjs`)
+
+```javascript
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+ title: 'Project Name',
+ description: 'Production Documentation Portal',
+ head: [
+ ['link', { rel: 'icon', href: '/logo.png' }]
+ ],
+
+ locales: {
+ root: {
+ label: 'العربية',
+ lang: 'ar',
+ dir: 'rtl',
+ themeConfig: {
+ nav: [
+ { text: 'الرئيسية', link: '/' },
+ { text: 'دليل الاستخدام', link: '/user_manual.ar' },
+ { text: 'المواصفات المعمارية', link: '/specs/architecture_spec.ar' },
+ { text: 'GitHub', link: 'https://github.com/organization/repo' }
+ ],
+ sidebar: [
+ {
+ text: '🚀 البدء السريع',
+ items: [
+ { text: 'نظرة عامة', link: '/' },
+ { text: 'دليل التثبيت', link: '/guide/getting-started.ar' }
+ ]
+ }
+ ]
+ }
+ },
+ en: {
+ label: 'English',
+ lang: 'en',
+ link: '/en/',
+ themeConfig: {
+ nav: [
+ { text: 'Home', link: '/en/' },
+ { text: 'User Manual', link: '/user_manual.ar' }
+ ]
+ }
+ }
+ },
+
+ themeConfig: {
+ logo: '/logo.png',
+ siteTitle: 'Project Name',
+ search: {
+ provider: 'local'
+ },
+ footer: {
+ message: 'Released under Apache-2.0 License',
+ copyright: 'Copyright © 2026 Engineering Team'
+ }
+ }
+});
+```
+
+---
+
+## 2. Luxury Design System Tokens (`docs/.vitepress/theme/custom.css`)
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Alexandria:wght@400;500;600;700;800;900&family=Cairo:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap');
+
+:root {
+ --vp-font-family-base: 'Cairo', sans-serif;
+ --vp-font-family-headings: 'Alexandria', sans-serif;
+ --vp-font-family-mono: 'JetBrains Mono', monospace;
+}
+
+/* RTL Navbar Flex Order */
+html[dir="rtl"] .VPNavBar .content-body {
+ display: flex !important;
+ flex-direction: row !important;
+ align-items: center !important;
+ width: 100%;
+}
+html[dir="rtl"] .VPNavBarTitle { order: 1 !important; margin-inline-end: 28px !important; }
+html[dir="rtl"] .VPNavBarMenu { order: 2 !important; margin-inline-end: auto !important; }
+html[dir="rtl"] .VPNavBarSearch { order: 3 !important; }
+html[dir="rtl"] .VPNavBarTranslations { order: 4 !important; }
+html[dir="rtl"] .VPNavBarAppearance { order: 5 !important; }
+html[dir="rtl"] .VPNavBarSocialLinks { order: 6 !important; }
+
+/* Hero Reading Direction in RTL: Text on Right, Logo on Left */
+.VPHomeHero .container {
+ display: flex !important;
+ align-items: center !important;
+ justify-content: space-between !important;
+}
+html[dir="rtl"] .VPHomeHero .container { flex-direction: row !important; }
+html[dir="rtl"] .VPHomeHero .main { order: 1 !important; text-align: right !important; flex: 1 1 60% !important; }
+html[dir="rtl"] .VPHomeHero .image { order: 2 !important; flex: 1 1 40% !important; display: flex !important; justify-content: center !important; }
+
+/* Single-Row Protected Hero Actions */
+.VPHomeHero .actions {
+ display: flex !important;
+ flex-direction: row !important;
+ align-items: center !important;
+ gap: 14px !important;
+ flex-wrap: nowrap !important;
+}
+.VPButton {
+ min-height: 48px !important;
+ height: 48px !important;
+ padding: 0 24px !important;
+ border-radius: 14px !important;
+ font-family: 'Alexandria', sans-serif !important;
+ font-weight: 700 !important;
+ font-size: 0.95rem !important;
+ white-space: nowrap !important;
+ word-break: keep-all !important;
+}
+
+/* 3-Column Luxury Feature Cards (Column Collapse Fix) */
+.VPFeatures .items {
+ display: flex !important;
+ flex-wrap: wrap !important;
+ margin: -10px !important;
+}
+.VPFeatures .item {
+ padding: 10px !important;
+ box-sizing: border-box !important;
+ width: 100% !important;
+ display: flex !important;
+}
+@media (min-width: 640px) { .VPFeatures .item { width: 50% !important; } }
+@media (min-width: 960px) { .VPFeatures .item { width: 33.333333% !important; } }
+
+.VPFeature {
+ border: 1px solid var(--vp-c-divider) !important;
+ border-radius: 20px !important;
+ background: var(--vp-c-bg-soft) !important;
+ backdrop-filter: blur(20px) !important;
+ padding: 28px !important;
+ width: 100% !important;
+ height: 100% !important;
+ box-sizing: border-box !important;
+}
+html[dir="rtl"] .VPFeature .title,
+html[dir="rtl"] .VPFeature .details {
+ text-align: right !important;
+ direction: rtl !important;
+ unicode-bidi: plaintext !important;
+}
+```
+
+---
+
+## 3. Quick Navigation Grid Markdown Template
+
+```markdown
+## 🧭 جدول المحتويات والمسارات السريعة
+
+.md` under five headings matching the dimensions above.
2. Update `docs/.doc-manifest.json` with `` and timestamp.
-3. Save local snapshot `.tidyfactor/doc-brief.snapshot.json` for deterministic drift detection.
+3. Save local snapshot `.tidyfactor/doc-brief.snapshot.yaml` for deterministic drift detection.
4. **Anti-Dual-Write Outbound Push (`--sync-brain`)**:
- Local markdown files are the sole Single Source of Truth.
- When `--sync-brain` is explicitly provided, export extracted architecture facts to Brain MCP via `extract_knowledge_item`.
---
-## ## Validation checklist
+## Validation checklist
- [ ] Context Delta Resolution executed before prompting user.
- [ ] `docs/.collected/.md` exists and has content under all five dimension headings.
diff --git a/references/workflows/generate-adr.md b/references/workflows/generate-adr.md
new file mode 100644
index 0000000..84fdb4b
--- /dev/null
+++ b/references/workflows/generate-adr.md
@@ -0,0 +1,41 @@
+# Workflow: generate-adr
+
+One outcome: an Architectural Decision Record saved to `docs/adr/NNNN-.md` and indexed in `docs/adr/README.md`, adhering to the MADR (Markdown Architectural Decision Records) standard.
+
+## Steps
+
+1. **Initialize ADR Directory & Determine Sequence**:
+ - Ensure `docs/adr/` exists.
+ - Scan existing files matching `docs/adr/NNNN-*.md`.
+ - Calculate next number: `0001` if empty, or increment highest existing number (e.g. `0002`, `0003`).
+
+2. **Establish Context & Problem Statement**:
+ - State the technical context clearly: What engineering problem or architectural need forced a decision?
+ - Identify Decision Drivers: Performance, developer experience, zero-runtime overhead, license compatibility, RTL support, security.
+
+3. **Formulate Considered Options**:
+ - List at least 2–3 viable alternatives (e.g. VitePress vs. MkDocs Material vs. Docsify; Medoo vs. Doctrine vs. Eloquent).
+ - For every option, provide an objective Pros & Cons analysis based on verifiable engineering facts.
+
+4. **Document Decision Outcome & Rationale**:
+ - Selected option: `Chosen option: [Option Name], because [positive arguments]`.
+ - Explain why alternatives were rejected without emotional bias.
+
+5. **Map Consequences & System Impact**:
+ - **Positive consequences**: Capabilities gained, performance improvements, simplified maintenance.
+ - **Negative consequences / Trade-offs**: Learning curve, dependencies introduced, migration effort.
+ - **Mitigation plan**: How trade-offs will be handled.
+
+6. **Write ADR & Update Index**:
+ - Write file `docs/adr/NNNN-.md` using `memory/adr-template.md`.
+ - Update `docs/adr/README.md` table of contents with status, title, and date.
+ - Run `python scripts/audit_docs.py docs/adr/` to verify link and credential hygiene.
+
+## Validation checklist
+
+- [ ] ADR file exists at `docs/adr/NNNN-.md` with 4-digit sequential numbering.
+- [ ] Conforms strictly to MADR structure in `memory/adr-template.md`.
+- [ ] At least two realistic alternatives were evaluated with pros/cons.
+- [ ] Tone conforms to `memory/tone-of-voice.md` (objective, technical, zero marketing fluff).
+- [ ] `docs/adr/README.md` index includes the new record.
+- [ ] Audited with `python scripts/audit_docs.py docs/adr/` and passed 100/100.
diff --git a/references/workflows/generate-changelog.md b/references/workflows/generate-changelog.md
new file mode 100644
index 0000000..fc64f79
--- /dev/null
+++ b/references/workflows/generate-changelog.md
@@ -0,0 +1,52 @@
+# Workflow: generate-changelog
+
+One outcome: a project-root `CHANGELOG.md` created or updated strictly conforming to **Keep a Changelog v1.1.0** and **SemVer 2.0.0**. Along with `README.md`, this is the authoritative Single Source of Truth (SSOT) for version releases, changes, and migration notes.
+
+## Steps
+
+1. **Locate or initialize `CHANGELOG.md`**:
+ - Check if `CHANGELOG.md` exists at the project root.
+ - If missing, load the Keep a Changelog template from `../memory/doc-templates.md` and initialize with standard header, description, and link definitions.
+
+2. **Extract change history & commit deltas**:
+ - Inspect git commit history:
+ ```bash
+ git log --oneline --no-merges -n 50
+ # Or between tags:
+ git log ..HEAD --oneline
+ ```
+ - Parse Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `perf:`, `chore:`, `sec:`).
+ - If non-git or manual changes are provided, align them with the verified codebase changes.
+
+3. **Categorize entries into Keep a Changelog standard sections**:
+ - `### 🚀 Added`: For new features, commands, or capabilities.
+ - `### 🔄 Changed`: For changes in existing functionality, refactors, or UX enhancements.
+ - `### ⚠️ Deprecated`: For once-stable features slated for removal in upcoming releases.
+ - `### 🗑️ Removed`: For features, deprecated APIs, or obsolete assets removed in this release.
+ - `### 🐛 Fixed`: For any bug fixes, link repairs, or error resolutions.
+ - `### 🔒 Security`: In case of vulnerability patches or credential hardening.
+
+4. **Determine SemVer version bump**:
+ - Load `../memory/changelog-rules.md`.
+ - `MAJOR` (X.0.0): Any breaking change or incompatible API/workflow modification.
+ - `MINOR` (0.X.0): Backward-compatible new features, commands, or workflows.
+ - `PATCH` (0.0.X): Backward-compatible bug fixes, link corrections, or documentation polish.
+
+5. **Format the version entry**:
+ - Structure: `## [X.Y.Z] - YYYY-MM-DD` (e.g. `## [1.8.0] - 2026-09-09`).
+ - If drafting work-in-progress, record changes under `## [Unreleased]`.
+ - Maintain strict reverse-chronological order (newest release at the top).
+
+6. **Validate & update metadata**:
+ - Run `python scripts/audit_docs.py CHANGELOG.md` to guarantee zero absolute machine URLs or credential leaks.
+ - Ensure atomic synchronization with `package.json`, `.tidyfactor`, `brand.yaml`, `brand.json`, and `README.md`.
+
+## Validation checklist
+
+- [ ] `CHANGELOG.md` exists at project root and follows Keep a Changelog v1.1.0 format
+- [ ] Version header strictly matches `## [X.Y.Z] - YYYY-MM-DD` or `## [Unreleased]`
+- [ ] All entries classified under valid sections (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`)
+- [ ] Entries are organized in reverse chronological order
+- [ ] SemVer bump is fully justified by the logged changes (Breaking → Major, Feat → Minor, Fix → Patch)
+- [ ] Zero sensitive data, API tokens, passwords, or absolute workstation paths (`file:///`) present
+- [ ] Audited with `python scripts/audit_docs.py CHANGELOG.md` and passed cleanly
diff --git a/references/workflows/generate-llmstxt.md b/references/workflows/generate-llmstxt.md
new file mode 100644
index 0000000..1d2a698
--- /dev/null
+++ b/references/workflows/generate-llmstxt.md
@@ -0,0 +1,56 @@
+# Workflow: generate-llmstxt
+
+One outcome: An authoritative, valid `/llms.txt` index file and `/llms-full.txt` bundle generated under `/docs` (or project root) conforming to the [llmstxt.org](https://llmstxt.org/) standard.
+
+---
+
+## Steps
+
+### 1. Identify Project Identity & Summary
+1. Read project root metadata (`package.json`, `composer.json`, `brand.yaml`, or root `README.md`).
+2. Extract the canonical project name for the required single `# H1` header.
+3. Formulate a dense 1-3 sentence blockquote summary (`> ...`) stating the project's purpose, key capabilities, and architecture.
+
+### 2. Crawl and Categorize Documentation
+1. Scan `/docs` (or existing documentation tree) for markdown files (`*.md`).
+2. Exclude internal files (`.doc-manifest.json`, changelog drafts, or raw collection dumps).
+3. Group discovered documents into clear `## H2` categories:
+ - `## Core Documentation` (Overview, Quickstart, Installation).
+ - `## Architecture & Governance` (ADRs, design patterns, invariants).
+ - `## API References` (endpoints, interfaces, contracts).
+ - `## Guides & Workflows` (how-tos, tutorials).
+
+### 3. Generate `/llms.txt` Index
+1. Format each entry as an annotated markdown item:
+ `- [Page Title](relative_or_canonical_url): Concise description of what this doc provides.`
+2. Ensure descriptions explicitly inform AI models when to load the page.
+3. Write the output to `docs/llms.txt` (and create a symlink or root copy at `llms.txt` if requested).
+
+### 4. Generate `/llms-full.txt` Bundle
+1. Concatenate the full markdown content of each categorized file in logical order.
+2. Separate each document with horizontal rules (`---`).
+3. Strip heavy base64 encoded images or redundant navigational chrome, retaining pure semantic markdown.
+4. Write the output to `docs/llms-full.txt`.
+
+### 5. Inject Discovery Headers
+1. If VitePress is used (`docs/.vitepress/config.mjs`), inject the `` tag into `head`:
+ ```javascript
+ head: [
+ ['link', { rel: 'alternate', type: 'text/markdown', href: '/llms.txt', title: 'LLM Overview' }],
+ ['link', { rel: 'alternate', type: 'text/markdown', href: '/llms-full.txt', title: 'Full LLM Documentation' }]
+ ]
+ ```
+2. If MkDocs is used (`mkdocs.yml`), register in extra head or include in template.
+3. If Docsify is used (`docs/index.html`), inject `` into ``.
+
+---
+
+## Validation checklist
+
+- [ ] Single unique `# H1` header present at line 1
+- [ ] Blockquote summary (`> ...`) immediately follows the H1 header
+- [ ] All documented links use annotated format `- [Title](url): Description`
+- [ ] Grouped logically under `## H2` categories
+- [ ] Generated `docs/llms.txt` and `docs/llms-full.txt` without syntax errors
+- [ ] No local machine absolute drive paths (`file:///C:/...` or `c:\...`) included in output
+- [ ] Discovery links (``) documented or configured for the active doc engine
diff --git a/references/workflows/init-docs.md b/references/workflows/init-docs.md
index b17fab0..f539280 100644
--- a/references/workflows/init-docs.md
+++ b/references/workflows/init-docs.md
@@ -1,17 +1,43 @@
# Workflow: init-docs
-One outcome: a working `/docs` scaffold plus a doc manifest, ready for `collect` and `generate` to populate.
+One outcome: a working `/docs` scaffold plus an aligned doc manifest, ready for `collect` and `generate` to populate.
-## Steps
+---
+
+## 📋 Step 0: Context Delta Resolution (CDL v2.0)
+
+Before prompting the user for documentation configuration, execute the mechanical resolution formula:
+
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+
+1. **Auto-Sensing on Disk**:
+ - `doc_engine`: Check for existing `mkdocs.yml` (selects `mkdocs_material`) or `docs/index.html` (selects `docsify_spa`). If neither exists, default to `mkdocs_material`.
+ - `target_scope`: Check project structure or `docs/.doc-manifest.json` (defaults to `full_codebase`).
+ - `audience_persona`: Read `brand.yaml` (or fallback `brand.json`) for `audience` / persona. If absent, default to `bilingual_developer`.
+ - For file sources marked with `track_staleness: true`, compare file hash/mtime against `.tidyfactor/doc-brief.snapshot.yaml`.
+2. **Fail-Open Brain MCP Acceleration**:
+ - Query `search_knowledge_base(query="documentation stack audience", scope="project")`.
+ - If Brain MCP is offline or returns empty, fail open silently (0ms latency penalty).
+3. **Structured Interactive Disclosure (DM-DA Mode A)**:
+ - Present any genuine $\text{Unknowns}$ in a crisp, non-robotic prompt with clear A/B/C/D choices and recommended defaults.
+ - Zero robotic preambles or lectures.
+4. **Local Snapshot Persistence (Anti-Dual-Write)**:
+ - Persist confirmed parameters to `.tidyfactor/doc-brief.snapshot.yaml`.
+
+---
+
+## 🛠️ Execution Steps
1. **Detect the stack(s) present** in the project root — PHP (`composer.json`), JS/TS (`package.json`, `tsconfig.json`), and any of React/Vue/Next (framework deps or config files). Note more than one if the project is mixed (e.g., a PHP API with a React front end).
2. **Create the folder tree** exactly per `memory/doc-tree.md` — no extra top-level folders, no missing ones. Do not create a folder for a doc type the project doesn't have yet (e.g., skip `docs/api/` for a project with no API surface) — see the "No Empty Structures" note in `doc-tree.md`.
-3. **Write `docs/.doc-manifest.json`** using the schema in `memory/doc-tree.md`, pre-filled with: detected stack(s), project name (from `composer.json`/`package.json`), and empty `collected` / `generated` tracking sections.
+3. **Write `docs/.doc-manifest.json`** using the schema in `memory/doc-tree.md`, pre-filled with: detected stack(s), project name (from `composer.json`/`package.json`), confirmed engine/audience from Step 0, and empty `collected` / `generated` tracking sections.
4. **Write a placeholder `docs/README.md` index** (one paragraph: what this `/docs` folder contains, and a note that it's generated/maintained by TidyFactor Doc) — this is the doc-site landing page, distinct from the project-root `README.md`.
5. **Report** what was created and what stack(s) were detected, and suggest `collect` as the next step.
## Validation checklist
+- [ ] Evaluated Context Delta Resolution formula before prompting user
+- [ ] Local decision snapshot persisted to `.tidyfactor/doc-brief.snapshot.yaml`
- [ ] `/docs` exists with only the subfolders `doc-tree.md` calls for given the detected stack(s) — nothing extra, nothing missing
- [ ] `docs/.doc-manifest.json` exists, is valid JSON, and matches the schema in `memory/doc-tree.md`
- [ ] `docs/README.md` (doc-site index) exists and is distinct in content from any project-root `README.md`
diff --git a/references/workflows/vitepress.md b/references/workflows/vitepress.md
new file mode 100644
index 0000000..cb01f45
--- /dev/null
+++ b/references/workflows/vitepress.md
@@ -0,0 +1,57 @@
+# Workflow: vitepress
+
+One outcome: A fully compiled, statically hosted VitePress documentation portal with custom luxury typography, surgical RTL flex order, and multi-language routing configured per `memory/vitepress-config.md`.
+
+---
+
+## Steps
+
+1. **Verify Environment & Dependencies:**
+ - Run `node --version` (require >= 18).
+ - Install VitePress: `npm install -D vitepress` (or verify package.json has `"vitepress": "^1.6.0"`).
+ - Inject doc scripts into root `package.json`:
+ ```json
+ "scripts": {
+ "docs:dev": "vitepress dev docs",
+ "docs:build": "vitepress build docs",
+ "docs:preview": "vitepress preview docs"
+ }
+ ```
+
+2. **Scaffold Directory Tree & Assets:**
+ - Ensure documentation markdown lives in `docs/`.
+ - Create `docs/.vitepress/config.mjs` using the master schema in `memory/vitepress-config.md`.
+ - Create `docs/.vitepress/theme/index.mjs` registering `custom.css`.
+ - Copy brand logo to `docs/public/logo.png`.
+
+3. **Configure Multi-Language Subdirectory Routing:**
+ - Enforce dedicated subdirectories for every supported locale to eliminate 404s:
+ - Arabic (Native Root): `docs/index.md`
+ - English: `docs/en/index.md`
+ - Additional growth locales: `docs/es/`, `docs/de/`, `docs/fr/`, `docs/pt/`, `docs/zh/`, `docs/fa/`.
+
+4. **Inject Luxury CSS & RTL Precision:**
+ - Write `docs/.vitepress/theme/custom.css` embedding Alexandria, Cairo, and JetBrains Mono fonts.
+ - Configure surgical RTL navbar flex order:
+ - Title/Logo (`order: 1`), Menu (`order: 2` with `margin-inline-end: auto`), Search (`order: 3`), Translations (`order: 4`), Appearance (`order: 5`), Social (`order: 6`).
+ - Align Hero reading hierarchy: Text on the right (`order: 1`), Logo on the left (`order: 2`).
+ - Protect Hero Action Buttons (CTAs): single-row layout (`flex-wrap: nowrap !important; white-space: nowrap !important`).
+ - Fix 3-Column Feature Cards: explicitly size `.VPFeatures .item` (`width: 33.333333% !important`) and apply `direction: rtl !important; unicode-bidi: plaintext !important` to prevent text or parentheses inversion.
+
+5. **Build & Validate:**
+ - Run `npm run docs:build` (must complete with **zero errors and zero broken links**).
+
+6. **Report Deployment Instructions:**
+ - Local dev server: `npm run docs:dev` (runs at `http://localhost:5173`).
+ - Production bundle: deploy the compiled output directory `docs/.vitepress/dist/`.
+
+---
+
+## Validation Checklist
+
+- [ ] `docs/.vitepress/config.mjs` exists with valid ESM syntax and full locales configuration
+- [ ] `docs/.vitepress/theme/custom.css` exists with Alexandria/Cairo fonts, single-row Hero CTAs, and 3-column card widths
+- [ ] Hero layout in RTL displays text/CTAs on the right and logo on the left
+- [ ] Every active locale index (`docs/index.md`, `docs/en/index.md`, etc.) exists on disk
+- [ ] `npm run docs:build` compiles cleanly with **0 errors and 0 dead links**
+- [ ] Clean relative links only — no machine workstation paths (`file:///C:/...`) or hardcoded secrets
diff --git a/scripts/audit_docs.py b/scripts/audit_docs.py
index 6a933bf..cb26a90 100644
--- a/scripts/audit_docs.py
+++ b/scripts/audit_docs.py
@@ -35,7 +35,11 @@
(r"[a-zA-Z]:\\wamp64\\www\\", "Banned internal workstation local path"),
]
-def audit_doc_file(file_path: Path) -> list:
+# Standard Keep a Changelog v1.1.0 sections
+VALID_CHANGELOG_SECTIONS = {"Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"}
+CHANGELOG_VERSION_PATTERN = re.compile(r"^##\s+\[(?:\d+\.\d+\.\d+|Unreleased)\](?:\s+-\s+\d{4}-\d{2}-\d{2})?$")
+
+def audit_doc_file(file_path: Path, check_links: bool = True) -> list:
issues = []
try:
content = file_path.read_text(encoding="utf-8", errors="replace")
@@ -43,6 +47,7 @@ def audit_doc_file(file_path: Path) -> list:
return [{"file": str(file_path), "severity": "high", "type": "read_error", "message": str(e)}]
lines = content.splitlines()
+ is_changelog = file_path.name.lower().startswith("changelog")
for idx, line in enumerate(lines, start=1):
# 1. Check for sensitive data leaks
@@ -61,13 +66,62 @@ def audit_doc_file(file_path: Path) -> list:
# 2. Check for banned absolute workstation paths & file:/// URLs
for pattern, desc in BANNED_URL_PATTERNS:
if re.search(pattern, line):
- issues.append({
- "file": str(file_path),
- "line": idx,
- "severity": "high",
- "type": "banned_absolute_path",
- "message": f"Banned workstation-specific path detected: {desc}. Use clean relative links or public URLs."
- })
+ # Ignore lines explaining the ban, rule definitions, or dummy placeholders
+ if not re.search(r"(?i)(prohibit|banned|prevent|never|don't|no\s+|avoid|clean relative|mandate|your_|example|redacted|\.\.\.|placeholder|<.+>|dummy)", line):
+ issues.append({
+ "file": str(file_path),
+ "line": idx,
+ "severity": "high",
+ "type": "banned_absolute_path",
+ "message": f"Banned workstation-specific path detected: {desc}. Use clean relative links or public URLs."
+ })
+
+ # 3. Check relative link integrity (strip code spans first to avoid flagging examples)
+ if check_links:
+ # Remove inline code backticks before checking active markdown links
+ line_no_code = re.sub(r"`[^`]*`", "", line)
+ # Match markdown links: [text](path)
+ for match in re.finditer(r"\[(?:[^\]]*)\]\(([^)]+)\)", line_no_code):
+ target_url = match.group(1).strip()
+ # Skip external, anchor-only, mailto, tel
+ if re.match(r"^(?:https?://|mailto:|tel:|#)", target_url, re.IGNORECASE):
+ continue
+ # Strip anchor or query params
+ clean_target = target_url.split("#")[0].split("?")[0].strip()
+ if not clean_target:
+ continue
+ # Resolve relative path
+ resolved = (file_path.parent / clean_target).resolve()
+ if not resolved.exists():
+ issues.append({
+ "file": str(file_path),
+ "line": idx,
+ "severity": "high",
+ "type": "broken_relative_link",
+ "message": f"Broken relative link '{target_url}' — target '{clean_target}' does not exist on disk."
+ })
+
+ # 4. CHANGELOG.md specific structure validation
+ if is_changelog:
+ version_headers = [l.strip() for l in lines if l.startswith("## ")]
+ if not version_headers:
+ issues.append({
+ "file": str(file_path),
+ "line": 1,
+ "severity": "high",
+ "type": "invalid_changelog_format",
+ "message": "CHANGELOG.md lacks standard release headers (expected format: '## [x.y.z] - YYYY-MM-DD' or '## [Unreleased]')."
+ })
+ else:
+ for vh in version_headers:
+ if not CHANGELOG_VERSION_PATTERN.match(vh):
+ issues.append({
+ "file": str(file_path),
+ "line": 1,
+ "severity": "low",
+ "type": "non_standard_version_header",
+ "message": f"Changelog version header '{vh}' does not strictly match Keep a Changelog SemVer pattern '## [X.Y.Z] - YYYY-MM-DD'."
+ })
return issues
diff --git a/scripts/clean_orphaned_assets.py b/scripts/clean_orphaned_assets.py
new file mode 100644
index 0000000..dc772e7
--- /dev/null
+++ b/scripts/clean_orphaned_assets.py
@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+TidyFactor Asset Hygiene & Orphan Cleaner
+Scans documentation markdown files for referenced image assets, detects orphaned files
+in assets/ directory, detects duplicate assets via SHA-256 hashing, and evaluates
+potential WebP compression savings.
+"""
+
+import sys
+import os
+import re
+import json
+import hashlib
+import argparse
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows console
+if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+ sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico"}
+
+def get_file_hash(file_path: Path) -> str:
+ hasher = hashlib.sha256()
+ try:
+ with open(file_path, "rb") as f:
+ while chunk := f.read(65536):
+ hasher.update(chunk)
+ return hasher.hexdigest()
+ except Exception:
+ return ""
+
+def scan_markdown_image_references(root_dir: Path) -> set:
+ referenced_filenames = set()
+ md_files = []
+
+ for f in root_dir.rglob("*.md"):
+ if any(part in f.parts for part in [".git", "node_modules", "vendor", "dist"]):
+ continue
+ md_files.append(f)
+
+ for md_file in md_files:
+ try:
+ content = md_file.read_text(encoding="utf-8", errors="replace")
+ except Exception:
+ continue
+
+ # 1. Match standard markdown image syntax: 
+ for match in re.finditer(r"!\[(?:[^\]]*)\]\(([^)]+)\)", content):
+ raw_url = match.group(1).strip().split("?")[0].split("#")[0]
+ if raw_url.startswith(("http://", "https://", "data:")):
+ continue
+ referenced_filenames.add(Path(raw_url).name.lower())
+
+ # 2. Match HTML img tags: 
+ for match in re.finditer(r"""]+src=["']([^"']+)["']""", content, re.IGNORECASE):
+ raw_url = match.group(1).strip().split("?")[0].split("#")[0]
+ if raw_url.startswith(("http://", "https://", "data:")):
+ continue
+ referenced_filenames.add(Path(raw_url).name.lower())
+
+ return referenced_filenames
+
+def analyze_assets(repo_root: Path, assets_dir: Path, delete_orphans: bool = False) -> dict:
+ if not assets_dir.exists() or not assets_dir.is_dir():
+ return {"error": f"Assets directory not found: {assets_dir}", "passed": True, "assets": []}
+
+ referenced_names = scan_markdown_image_references(repo_root)
+
+ asset_files = []
+ for f in assets_dir.iterdir():
+ if f.is_file() and f.suffix.lower() in IMAGE_EXTENSIONS:
+ asset_files.append(f)
+
+ # 1. Detect duplicates via SHA-256
+ hash_map = {}
+ duplicates = []
+ orphaned_files = []
+ webp_candidates = []
+ total_size = 0
+
+ for f in asset_files:
+ size = f.stat().st_size
+ total_size += size
+ f_hash = get_file_hash(f)
+ f_name_lower = f.name.lower()
+
+ if f_hash in hash_map:
+ duplicates.append({
+ "file": str(f.relative_to(repo_root)),
+ "duplicate_of": str(hash_map[f_hash]["path"].relative_to(repo_root)),
+ "size_bytes": size,
+ "sha256": f_hash
+ })
+ else:
+ hash_map[f_hash] = {"path": f, "size": size}
+
+ # Check orphan status
+ is_referenced = f_name_lower in referenced_names
+ if not is_referenced:
+ orphaned_files.append({
+ "file": str(f.relative_to(repo_root)),
+ "size_bytes": size,
+ "deleted": False
+ })
+
+ # Check WebP optimization candidate (PNG/JPG > 50KB)
+ if f.suffix.lower() in {".png", ".jpg", ".jpeg"} and size > 51200:
+ estimated_webp_size = int(size * 0.25) # ~75% reduction
+ webp_candidates.append({
+ "file": str(f.relative_to(repo_root)),
+ "current_size_bytes": size,
+ "estimated_webp_bytes": estimated_webp_size,
+ "estimated_savings_bytes": size - estimated_webp_size
+ })
+
+ # Execute deletion if requested
+ if delete_orphans and orphaned_files:
+ for item in orphaned_files:
+ try:
+ target_to_del = repo_root / item["file"]
+ target_to_del.unlink()
+ item["deleted"] = True
+ except Exception as e:
+ item["delete_error"] = str(e)
+
+ passed = len(orphaned_files) == 0 and len(duplicates) == 0
+
+ return {
+ "repo_root": str(repo_root),
+ "assets_dir": str(assets_dir),
+ "total_assets_scanned": len(asset_files),
+ "total_size_bytes": total_size,
+ "orphaned_count": len(orphaned_files),
+ "orphaned_files": orphaned_files,
+ "duplicates_count": len(duplicates),
+ "duplicates": duplicates,
+ "webp_optimization_candidates": webp_candidates,
+ "passed": passed
+ }
+
+def main():
+ parser = argparse.ArgumentParser(description="TidyFactor Asset Hygiene & Orphan Cleaner")
+ parser.add_argument("repo_root", nargs="?", default=".", help="Root directory of the skill or repo (default: .)")
+ parser.add_argument("--assets-dir", default="assets", help="Relative path to assets directory (default: assets)")
+ parser.add_argument("--delete-orphans", action="store_true", help="Delete orphaned asset files directly")
+ parser.add_argument("--json", action="store_true", help="Output pure JSON format")
+
+ args = parser.parse_args()
+ root_path = Path(args.repo_root).resolve()
+ assets_path = (root_path / args.assets_dir).resolve()
+
+ result = analyze_assets(root_path, assets_path, delete_orphans=args.delete_orphans)
+
+ if args.json:
+ print(json.dumps(result, indent=2, ensure_ascii=False))
+ else:
+ status_str = "[PASS]" if result.get("passed") else "[WARN]"
+ print(f"\n{status_str} Asset Hygiene & Orphan Scanner — Scanned: {result.get('total_assets_scanned', 0)} assets ({result.get('total_size_bytes', 0):,} bytes)")
+ print(f"Orphaned Assets: {result.get('orphaned_count', 0)} | Duplicate Assets: {result.get('duplicates_count', 0)}\n")
+
+ if result.get("duplicates"):
+ print(" ⚠️ Duplicate Assets Found:")
+ for d in result["duplicates"]:
+ print(f" - {d['file']} (Duplicate of {d['duplicate_of']}, size: {d['size_bytes']:,} B)")
+
+ if result.get("orphaned_files"):
+ print(" ⚠️ Orphaned Assets (Not linked in any .md):")
+ for o in result["orphaned_files"]:
+ del_str = " [DELETED]" if o.get("deleted") else ""
+ print(f" - {o['file']} ({o['size_bytes']:,} B){del_str}")
+
+ if result.get("webp_optimization_candidates"):
+ print("\n 💡 WebP Optimization Recommendations (>50KB PNG/JPG):")
+ for w in result["webp_optimization_candidates"]:
+ print(f" - {w['file']} (Current: {w['current_size_bytes']:,} B -> Est. WebP: {w['estimated_webp_bytes']:,} B, Save: ~{w['estimated_savings_bytes']:,} B)")
+
+ print()
+
+ sys.exit(0 if result.get("passed") else 1)
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/build-skill.js b/tools/build-skill.js
index 4ab0da9..37d7121 100644
--- a/tools/build-skill.js
+++ b/tools/build-skill.js
@@ -28,6 +28,7 @@ const ROOT_COPIES = [
"tools",
"bin",
"brand.json",
+ "brand.yaml",
".tidyfactor",
"package.json",
"AGENTS.md",
• `api_surface_only` (Public exports, routes, and client SDKs)
• `internal_architecture` (Developer onboarding, ADRs, module contracts)
• `end_user_docs` (User guides, tutorials, setup walkthroughs) | `full_codebase` | When request asks to "document this project" without specifying audience or depth. | +| **D2** | **Publishing Platform Engine** | • `mkdocs_material` (Static HTML compilation, lunr offline search, bilingual i18n)
• `docsify_spa` (Zero-build client runtime SPA, instant markdown preview)
• `static_markdown` (Raw markdown files under `/docs` with root README) | `mkdocs_material` (if python available) / `docsify_spa` | When user has not configured `mkdocs.yml` or `docs/index.html`. | +| **D3** | **Target Persona & Linguistic Register** | • `bilingual_developer` (Arabic/English parallel guides, technical terminology)
• `api_consumer` (Strict English technical docs, contract signatures)
• `internal_maintainer` (Architecture rationale, git commit history context)
• `end_user` (Simplified bilingual non-technical user documentation) | `bilingual_developer` | When project has not specified language or target reader in `brand.yaml`. | +| **D4** | **Hygiene & Redaction Policy** | • `strict_zero_leak` (Mandatory automated regex masking of all IPs, DB passwords, API tokens)
• `public_sdk_redaction` (Scrub all internal routes, mock endpoints only)
• `internal_audit_permissive` (Permit local loopback `127.0.0.1` and dummy sample envs) | `strict_zero_leak` | Mandatory for all public or open-source documentation generation. | +| **D5** | **Collection Depth & Extraction Dimensions** | • `full_5_dimensions` (Source AST + Git commit rationale + Env vars + Personas + Error patterns)
• `signatures_and_types` (Public function/class docblocks only)
• `architecture_and_rationale` (Module boundaries, ADRs, and commit history) | `full_5_dimensions` | Decides computational depth of subsequent `collect` workflow. | + +--- + +## 🧭 Dual Operational Modes (DM-DA) + +``` +[CDL v2.0 Protocol] + │ + ▼ + Context Delta Resolution ──(Unknowns = ∅)──► Instant Baseline Confirmation + │ + ├─► [MODE A] 🎯 Smart 3-Round Protocol (Deterministic alignment in 3 rounds) + │ Round 1: Purpose & Target Audience + │ Round 2: Engine & Architecture + │ Round 3: Boundaries, Hygiene & Safe Defaults + │ └── Escalation Gate: Confirm OR Escalate to Mode B + │ + └─► [MODE B] 🔥 Relentless Debate & Interview (Debate Mode) + Continuous multi-turn interrogation challenging assumptions + Forces binary trade-offs (static vs SPA, brevity vs depth) + Terminates strictly on: "END DEBATE" / "اعتماد" + Emits: architectural_debate_synthesis.md +``` + +### [MODE A] 🎯 Smart 3-Round Protocol (الارتجال الذكي المقيد) +- **Round 1: Purpose & Scope (D1 + D3)**: Pinpoint primary documentation consumer and technical scope. +- **Round 2: Architecture & Engine (D2 + D5)**: Select publishing engine and depth of code extraction. +- **Round 3: Hygiene & Safe Defaults (D4 + Remaining)**: Enforce security scrubbing rules and apply defaults. +- **Strict Termination**: Finishes at Round 3, saves snapshot, and presents the Escalation Gate: + > *"هل تعتمد هذه البنية المبدئية للبدء فوراً، أم تفضل تفعيل [نمط المناظرة 🔥 Debate Mode] لتفكيك الافتراضات واختبار صلابة الهيكلية التوثيقية؟"* + +### [MODE B] 🔥 Relentless Debate & Interview (الاستجواب والمناظرة اللانهائية — Debate Mode) +- **Activation**: Direct `/debate`, or Mode A Round 3 escalation. +- **Behavior**: + - Relentless multi-turn counter-questioning challenging documentation choices: + - *"Why choose Docsify client-side SPA if SEO and offline indexability are critical for external developers?"* + - *"Why document internal private methods if the primary goal is public API adoption?"* + - *"How will the team prevent confidential server IPs and auth secrets from slipping into generated guides?"* + - *"If the documentation is bilingual Arabic/English, how will code snippets and RTL UI callouts remain visually coherent without layout breakages?"* + - Exposes anti-patterns: bloated doc sets nobody reads, duplicate API references, undocumented environment configurations. + - Forces binary, uncompromising trade-offs. +- **Termination**: Ends **only** when user signals `"END DEBATE"` or `"اعتماد"`. +- **Deliverables**: + - Generates formal synthesis: `docs/architectural_debate_synthesis.md`. + - Persists confirmed parameters to `.tidyfactor/doc-brief.snapshot.yaml` and `.tidyfactor/doc-brief.md`. + +--- + +## ⚡ Boolean Skip Conditions (Deterministic Bypass) + +Skip interactive questioning and adopt safe defaults immediately if ANY condition is met: +1. **Existing Snapshot**: `.tidyfactor/doc-brief.snapshot.yaml` exists and `track_staleness` confirms zero file drift. +2. **Explicit User Declaration**: User specifies complete parameters in the prompt (e.g. *"Init MkDocs Material docs for public API with strict redaction"*). +3. **Direct Stack Command**: User calls specific engine commands directly (`/mkdocs` or `/docsify`). +4. **Maintenance Mode**: An audit (`audit_docs`) or validation run (`validate_skill.py`) preserves current configurations. diff --git a/references/memory/doc-templates.md b/references/memory/doc-templates.md index 8bb810d..50799a9 100644 --- a/references/memory/doc-templates.md +++ b/references/memory/doc-templates.md @@ -1,4 +1,4 @@ - + # Memory: doc-templates Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings. @@ -72,3 +72,31 @@ Full reference: [`/docs`](./docs/README.md) ## Related
+
+| 🚀 البدء والأدوات | 💼 التطبيقات وحزم العمل | 🏛️ المعمارية العميقة |
+|---|---|---|
+| • [دليل التثبيت](/guide/getting-started.ar)
• [مرجع الطرفية](/tools/cli.ar) | • [تطبيقات الإنتاجية](/apps/productivity.ar)
• [حزمة الأعمال](/apps/office-suite.ar) | • [بنية الذاكرة](/architecture/memory-and-search.ar)
• [المواصفات الفنية](/specs/architecture_spec.ar) | + +
+```
diff --git a/references/workflows/audit.md b/references/workflows/audit.md
new file mode 100644
index 0000000..cd1f305
--- /dev/null
+++ b/references/workflows/audit.md
@@ -0,0 +1,42 @@
+# Workflow: audit
+
+One outcome: a deterministic documentation quality & hygiene audit report verifying zero credential leaks, zero banned machine paths, 100% relative link integrity, and valid CHANGELOG formatting.
+
+## Steps
+
+1. **Determine the target path**:
+ - If user specified a file or folder (e.g. `docs/`, `README.md`, `CHANGELOG.md`), audit that target.
+ - Otherwise, default to full documentation sweep: `docs/`, `README.md`, `README.ar.md`, `CHANGELOG.md`.
+
+2. **Run deterministic auditor**:
+ - Execute the native Python auditing tool:
+ ```bash
+ python scripts/audit_docs.py docs/
+ python scripts/audit_docs.py README.md
+ python scripts/audit_docs.py CHANGELOG.md
+ ```
+ - For machine-readable output or CI pipeline integration:
+ ```bash
+ python scripts/audit_docs.py docs/ --json
+ ```
+
+3. **Analyze findings**:
+ - **Critical issues (Score -30 each)**: Plaintext secrets, leaked API keys, database passwords, or private tokens.
+ - **High issues (Score -15 each)**: Banned absolute workstation paths (`file:///C:`, `\wamp64\www\`), broken relative markdown links pointing to missing files, missing CHANGELOG headers.
+ - **Low issues**: Non-standard changelog version headers or minor formatting irregularities.
+
+4. **Remediate detected issues**:
+ - Redact any sensitive tokens into safe RFC placeholders (`EXAMPLE_KEY_1234567890ABCDEFGH`).
+ - Fix broken relative links to point to valid paths or update link targets.
+ - Convert absolute filesystem URLs to clean relative markdown paths (`./docs/README.md`).
+
+5. **Re-run verification**:
+ - Re-execute the auditor until a clean score of **100/100 [PASS]** is achieved.
+
+## Validation checklist
+
+- [ ] All target documentation files scanned by `scripts/audit_docs.py`
+- [ ] Overall score is 100/100 (`passed: true`) with 0 critical and 0 high issues
+- [ ] Zero sensitive tokens or credentials present across all scanned files
+- [ ] All relative links verified to exist on disk (zero broken relative links)
+- [ ] CHANGELOG.md conforms to Keep a Changelog v1.1.0 standard headers
diff --git a/references/workflows/brief.md b/references/workflows/brief.md
new file mode 100644
index 0000000..73cfd3c
--- /dev/null
+++ b/references/workflows/brief.md
@@ -0,0 +1,105 @@
+# Workflow: brief
+
+One outcome: a validated documentation architectural brief and local snapshot, establishing all governance parameters before scaffolding or code parsing begins.
+
+---
+
+## 📋 Step 0: Context Delta Resolution (CDL v2.0)
+
+Before querying the user, deterministically evaluate the Context Delta formula:
+
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+
+1. **Local Auto-Sensing on Disk**:
+ - Inspect `package.json`, `composer.json`, `tsconfig.json` for stack identification.
+ - Check existing documentation markers (`mkdocs.yml`, `docs/index.html`, `docs/.doc-manifest.json`).
+ - Read `brand.yaml` (fallback `brand.json`) for project name, audience, and license.
+ - Check `.tidyfactor/doc-brief.snapshot.yaml`: if present and file hashes match (`track_staleness: true`), resolve all decisions immediately.
+2. **Fail-Open Brain MCP Acceleration**:
+ - Query `search_knowledge_base(query="documentation architecture", scope="project")`.
+ - If Brain MCP is absent, disabled, or empty, proceed with 0ms silent fallback.
+3. **Delta Evaluation**:
+ - If $\text{Unknowns} = \emptyset$: Proceed immediately to Step 2 (persist snapshot) with zero conversational overhead.
+ - If $\text{Unknowns} \neq \emptyset$: Proceed to Step 1 using the requested Operational Mode.
+
+---
+
+## 🧭 Step 1: Operational Mode Execution (Native Modal Wizard Contract)
+
+> [!IMPORTANT]
+> **Zero Static Text Questionnaires (`❌`)**:
+> The agent is **STRICTLY FORBIDDEN** from outputting questions, choices, or debate trade-offs as plain written markdown text in the chat.
+> The agent **MUST** invoke the platform's native interactive question tool (`ask_question` in Antigravity IDE) to render a structured modal wizard with selectable options and recommended defaults.
+
+---
+
+### [MODE A] 🎯 Smart 3-Round Protocol (الارتجال الذكي المقيد)
+*Fast-track structured alignment via native modal wizards.*
+
+- **Round 1: Purpose & Target Persona (D1 & D3)**:
+ - Invoke `ask_question`:
+ - Question 1: "ما هو النطاق الأساسي لتوثيق المشروع؟"
+ Options: `"(Recommended) full_codebase — توثيق شامل للـ API والمعمارية وأدلة التشغيل"`, `"api_surface_only — توثيق نقاط النهاية وواجهات الـ API فقط"`, `"internal_architecture — توثيق المعمارية وتهيئة المطورين الداخليين"`, `"end_user_docs — أدلة استخدام مبسطة للمستخدم النهائي"`
+ - Question 2: "ما هي شريحة القراء والتوجه اللغوي المستهدف؟"
+ Options: `"(Recommended) bilingual_developer — توثيق فني ثنائي باللغتين العربية والإنجليزية"`, `"api_consumer — توثيق تقني صارم بالإنجليزية لمستهلكي الـ API"`, `"internal_maintainer — توثيق معطيات القرارات وسياق المطورين"`, `"end_user — توثيق مبسط لغير التقنيين"`
+- **Round 2: Architecture & Engine (D2 & D5)**:
+ - Invoke `ask_question`:
+ - Question 1: "ما هو محرك نشر وعرض التوثيق المعتمد؟"
+ Options: `"(Recommended) mkdocs_material — توليد موقع ثابت سريع مع بحث محلي ودعم ثنائي"`, `"docsify_spa — موقع تفاعلي فوري خفيف دون الحاجة لأي تجميع (Zero-Build)"`, `"static_markdown — ملفات Markdown خام قياسية تحت مجلد /docs"`
+ - Question 2: "ما هو عمق الاستقراء البرمجي المطلوب من الكود؟"
+ Options: `"(Recommended) full_5_dimensions — استقراء الأبعاد الخمسة (AST + Git History + Env + Personas + Errors)"`, `"signatures_and_types — مراجع الدوال والأنواع المصدرة فقط"`, `"architecture_and_rationale — المعمارية والحدود وسياق الـ Commits"`
+- **Round 3: Hygiene & Safe Defaults (D4 & Escalation Gate)**:
+ - Invoke `ask_question`:
+ - Question: "ما هي سياسة حجب البيانات الحساسة والأمان؟"
+ Options: `"(Recommended) strict_zero_leak — حظر وتطهير آلي صارم لكافة المفاتيح وكلمات المرور وعناوين IP"`, `"public_sdk_redaction — حجب المسارات الداخلية مع اعتماد مسارات محاكاة"`, `"internal_audit_permissive — السماح بعناوين Loopback المحلية وعينات التهيئة"`
+ - **Escalation Gate (Modal Wizard)**:
+ - Invoke `ask_question`:
+ - Question: "اكتملت أبعاد التوثيق المبدئية. هل ترغب في اعتمادها فوراً أم تفعيل نمط المناظرة (Debate Mode) لتحدي القرارات؟"
+ - Options: `"(Recommended) اعتماد البنية المبدئية والبدء فوراً في التوثيق"`, `"تفعيل نمط المناظرة المعمارية (Debate Mode)"`
+
+---
+
+### [MODE B] 🔥 Relentless Debate & Interview (الاستجواب والمناظرة اللانهائية — Debate Mode)
+*Deep architectural interrogation via step-by-step interactive question modals.*
+
+- **Trigger**: Command `/debate`, explicit user prompt ("مناظرة" / "استجوبني"), or escalation from Round 3 of Mode A.
+- **Modal Interrogation Protocol**:
+ - The agent poses **ONE architectural challenge at a time** strictly via `ask_question`.
+ - The question title encapsulates the dilemma (e.g. *"معضلة الصيانة اللغوية: هل نعتمد أتمتة صارمة لكافة اللغات أم نحصر التحديث الحي في لغتين أساسيتين؟"*).
+ - The options provide binary, concrete trade-offs with explicit costs:
+ - Option 1: `"(Recommended) حصر التحديث الحي المستمر على اللغتين الأساسيتين (AR/EN) واعتماد ملخصات تنفيذية للغات الأخرى"`
+ - Option 2: `"فرض أتمتة كاملة في الـ CI للغات الثماني بالتوازي مع إيقاف البناء عند أي نقص"`
+ - Each selection by the user leads to the next focused counter-question via `ask_question` exploring dependency and edge cases.
+- **Termination Constraint**: Continues turn-by-turn until the user explicitly selects an option marked `اعتماد القرارات المعمارية وإنهاء المناظرة` or types `"END DEBATE"` / `"اعتماد"`.
+- **Debate Artifact**: Emits formal synthesis at `docs/architectural_debate_synthesis.md` capturing all settled decisions, discarded alternatives, and technical rationale.
+
+---
+
+## 💾 Step 2: SSOT Local Persistence & Outbound Push
+
+1. **Write Local SSOT**:
+ - Write `.tidyfactor/doc-brief.snapshot.yaml` with resolved keys, mtimes, and hashes.
+ - Write `.tidyfactor/doc-brief.md` containing human-readable brief summary.
+2. **Outbound Push (`--sync-brain`)**:
+ - If `--sync-brain` flag was provided, invoke `extract_knowledge_item` to persist documentation metadata to sovereign Brain MCP.
+ - Local files remain the authoritative Single Source of Truth.
+
+---
+
+## 🎯 Step 3: Handoff
+
+- If `/docs` directory is uninitialized ➔ Hand off to `workflows/init-docs.md`.
+- If `/docs` exists and documentation needs generation ➔ Hand off to `workflows/collect.md` followed by `workflows/generate-*.md`.
+
+---
+
+## Validation checklist
+
+- [ ] Context Delta Resolution computed before asking user any questions
+- [ ] No questions asked for facts already discoverable from disk
+- [ ] All interactive questions in Mode A and Mode B were presented exclusively via native modal wizard (ask_question), with zero static text surveys in chat
+- [ ] Followed selected mode (Mode A terminated at Round 3; Mode B terminated only on "END DEBATE" / "اعتماد")
+- [ ] If Mode B was executed, generated `docs/architectural_debate_synthesis.md`
+- [ ] Local snapshot persisted to `.tidyfactor/doc-brief.snapshot.yaml`
+- [ ] Human-readable brief saved to `.tidyfactor/doc-brief.md`
+- [ ] No actual doc pages or API references written during this workflow
diff --git a/references/workflows/collect.md b/references/workflows/collect.md
index 519c5d1..bcf787e 100644
--- a/references/workflows/collect.md
+++ b/references/workflows/collect.md
@@ -25,7 +25,11 @@ $$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \t
Run all five collection dimensions from `memory/collection-sources.md` against the target:
-1. **Code parsing**: Extract existing docblocks/comments, function/method/class signatures, exported types, and public surface area directly from source. Flag anything already documented inline.
+1. **Code parsing & Docblock Scraping**:
+ - **For PHP**: Scan for standard PHPDoc annotations (`@param [type] $var [description]`, `@return [type]`, `@throws [exception]`, `@deprecated`, `@var`). Extract class properties, public method signatures, interface implementations, and parameter typehints (`string`, `int`, `array`, `?callable`).
+ - **For JavaScript / TypeScript**: Scan for JSDoc / TSDoc annotations (`@param {type} name description`, `@returns {type}`, `@typedef`, `@template`, `@async`, `@example`). For TypeScript, extract exported interfaces, types, enums, and React/Vue component prop types directly from AST definitions.
+ - Cross-reference with `memory/stacks/php.md` or `memory/stacks/js-ts.md` to ensure exact standard compliance.
+ - Flag undocumented public surface area or stale docblocks where signature types diverge from comments.
2. **Commit history**: Read `git log` and available PR descriptions for target files. Pull out *why* behind non-obvious code (tradeoffs, rationale, bug fixes).
3. **Runtime & environment**: Enumerate required environment variables, config files, software dependencies (with version constraints), and resource limits. **MANDATORY**: Scrub and redact any actual secrets, production server IPs, database passwords, or private API tokens—record only variable names and generic placeholders.
4. **User persona tracing**: Identify who reads docs for this target (API consumers, internal maintainers, end-users) and map facts accordingly.
@@ -37,14 +41,14 @@ Run all five collection dimensions from `memory/collection-sources.md` against t
1. Write structured notes to `docs/.collected/• [مرجع الطرفية](/tools/cli.ar) | • [تطبيقات الإنتاجية](/apps/productivity.ar)
• [حزمة الأعمال](/apps/office-suite.ar) | • [بنية الذاكرة](/architecture/memory-and-search.ar)
• [المواصفات الفنية](/specs/architecture_spec.ar) | + +