@tidyfactor/doc 1.3.0

package/README.md

@@ -0,0 +1,198 @@
+<div align="center">
+
+# 📚 TidyFactor Doc `v1.3.0`
+### Automated Codebase Interview, API Generator & Dual-Engine Publishing Platform (MkDocs Material & Docsify)
+
+**Building accurate, maintainable, secure, and browsable documentation for the era of Human-Agent Collaboration.**
+
+[![npm version](https://img.shields.io/npm/v/@tidyfactor/doc.svg?style=for-the-badge&color=4F46E5)](https://www.npmjs.com/package/@tidyfactor/doc)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-TidyFactor%2FDoc-181717.svg?style=for-the-badge&logo=github)](https://github.com/TidyFactor/Doc)
+[![Security Redaction Certified](https://img.shields.io/badge/Security-Redaction%20Certified-emerald.svg?style=for-the-badge)](#-enterprise-security--sanitization-guarantees)
+[![Clean Links Verified](https://img.shields.io/badge/Links-Clean%20%26%20Relative-cyan.svg?style=for-the-badge)](#-clean-relative-links--navigation-standards)
+[![Universal AI Agents](https://img.shields.io/badge/AI%20Agents-Universal%20Compatibility-4285F4.svg?style=for-the-badge)](README.md)
+[![RTL Ready](https://img.shields.io/badge/RTL-Native%20Arabic-emerald.svg?style=for-the-badge)](README.ar.md)
+
+[🌐 Official Website](https://tidyfactor.com/) • [📚 Documentation](https://tidyfactor.com/documentation) • [🤝 Partner (Alwkala)](https://alwkala.com/) • [⚡ Commands](#-commands--the-4-phase-documentation-lifecycle) • [🛡️ Security Guarantees](#-enterprise-security--sanitization-guarantees) • [📖 Read in Arabic (بالعربية)](README.ar.md)
+
+<br/><br/>
+
+<p align="center">
+  <img src="assets/hero-banner.png" alt="TidyFactor Doc Hero Banner" width="100%" />
+</p>
+
+</div>
+
+---
+
+> [!NOTE]
+> **TidyFactor Doc** is a deterministic documentation engine and Docsify architecture suite built for AI coding agents (*Google Antigravity, Claude Code, Cursor, Codex, Windsurf*). It systematically interviews a codebase—parsing source AST docblocks, Git commit rationale, runtime environment variables, and error patterns—to produce pristine, browsable `/docs` portals with zero manual drift, zero credential leaks, and zero broken local paths.
+
+---
+
+## 🌟 Value Proposition & Why TidyFactor Doc?
+
+| For Developers & Tech Leads | For AI Coding Agents | For Open-Source & Enterprise |
+|---|---|---|
+| **Zero Manual Writing**: Non-destructive codebase analysis extracts architecture, API signatures, and setup flows directly from source. | **Token-Efficient Routing**: Router `SKILL.md` (~350 tokens) dispatches isolated workflows with exact memory context. | **Instant Docsify Portal**: One command transforms `/docs` into a responsive, searchable documentation website. |
+| **Zero Sensitive Leakage**: Enforces automated redaction of API keys, passwords, database credentials, and production IPs. | **Fact-Grounded Only**: Agents are constrained from hallucinating signatures or parameters—everything traces to findings. | **Universal Polyglot**: Native templates for PHP 8+, TypeScript, JavaScript ES Modules, and React/Vue/Next components. |
+| **Clean Relative Linking**: Eliminates broken `file:///` and machine paths (`C:\...`), guaranteeing portable markdown. | **Deterministic Validation**: Every workflow has an explicit checklist and manifest tracking in `docs/.doc-manifest.json`. | **Bilingual by Design**: Native LTR/RTL support with curated typography pairings (Inter + Cairo/Tajawal). |
+
+---
+
+## 🔄 The 4-Phase Documentation Lifecycle
+
+`tidyfactor-doc` structures documentation generation into 4 sequential, deterministic phases:
+
+```mermaid
+graph LR
+    P1["1. Init (Scaffold)"] --> P2["2. Collect (Interview)"]
+    P2 --> P3["3. Generate (Authoring)"]
+    P3 --> P4["4. Docsify (Publish)"]
+```
+
+```
+[ Phase 1: init ] ──> Creates /docs directory tree & .doc-manifest.json
+         │
+[ Phase 2: collect ] ─> Gathers 5 dimensions (Code AST, Git History, Env, Personas, Errors) into docs/.collected/
+         │
+[ Phase 3: generate ] ─> Produces API refs, Guides, Inline comments, or Root README from collected facts
+         │
+[ Phase 4: docsify ] ─> Assembles index.html & _sidebar.md for instant static browser preview & hosting
+```
+
+---
+
+## 🏛️ Commands & Workflows Registry
+
+| Intent & User Request | Command | Loaded Workflow & Memory | Output Artifact |
+|---|---|---|---|
+| **"Set up docs for this project"** / "scaffold /docs" | `init` | `workflows/init-docs.md`<br>`memory/doc-tree.md` | `/docs` scaffold, `docs/.doc-manifest.json`, `docs/README.md` |
+| **"Document this codebase"** / "gather facts for module X" | `collect` | `workflows/collect.md`<br>`memory/collection-sources.md` | `docs/.collected/<target>.md` (5-dimensional structured analysis) |
+| **"Write API reference"** / "generate docs for endpoints" | `generate` | `workflows/generate-api.md`<br>`memory/doc-templates.md`<br>`memory/stacks/*.md` | `docs/api/<target>.md` (parameter tables, returns, errors, examples) |
+| **"Write setup guide"** / "create architecture runbook" | `generate` | `workflows/generate-guide.md`<br>`memory/doc-templates.md` | `docs/guides/<purpose-slug>.md` (focused, single-purpose guide) |
+| **"Generate project README"** / "update root README" | `generate` | `workflows/generate-readme.md`<br>`memory/doc-templates.md` | Root `README.md` (overview, install, env vars, quick start) |
+| **"Add inline docblocks"** / "document public functions" | `generate` | `workflows/generate-inline.md`<br>`memory/stacks/*.md` | Direct source code edit with PHPDoc / JSDoc / TSDoc comments |
+| **"Turn /docs into Docsify site"** / "deploy doc portal" | `docsify` | `workflows/docsify.md`<br>`memory/docsify-config.md` | `docs/index.html` + `docs/_sidebar.md` (instant web portal) |
+
+---
+
+## 🛡️ Enterprise Security & Sanitization Guarantees
+
+In modern AI agent workflows, sensitive credentials and private configurations frequently leak into documentation. `tidyfactor-doc` implements strict, non-negotiable redaction rules (**Constraint 6**):
+
+| Secret / Sensitive Category | Prohibited Leaks | Mandatory Safe Replacement |
+|---|---|---|
+| **API Tokens & Secret Keys** | `sk_live_948f98a7c1b2...` | `EXAMPLE_TOKEN_1234567890ABCDEFGH` or `YOUR_API_KEY` |
+| **Passwords & DB Credentials** | `RootP@ssw0rd2026!` | `your_secret_password` |
+| **Server & Host IPs** | `192.168.1.50`, `45.33.21.99` | `203.0.113.1` (RFC 5737 documentation prefix) |
+| **Workstation File URIs** | `file:///C:/path/to/project/...` | `./docs/guides/` or `project-root/` |
+| **Internal Development URLs** | `http://localhost:8080/admin` | `https://api.example.com` or `http://localhost:PORT` |
+| **User Home Directories** | `/home/developer/workspace/...` | `~/project` or `/path/to/project` |
+
+---
+
+## 🌐 Clean Relative Links & Navigation Standards
+
+To guarantee that documentation renders flawlessly on GitHub, GitLab, Docsify, and local markdown viewers, `tidyfactor-doc` enforces **Constraint 7**:
+
+- ❌ **Zero Absolute Drive Paths**: Never output `file:///` URLs or workstation drive letters (`C:\...`, `/Users/...`).
+- ✅ **Clean Markdown Relative Links**: All internal document links use standard relative paths (e.g. `[Architecture Guide](./guides/architecture.md)`).
+- ✅ **Docsify Persistent Subfolder Routing**: Configures `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` with root-relative leading slashes (`/guides/...`, `/api/...`) to eliminate 404 broken sidebars when navigating deep routes.
+- ✅ **Localized Docs Inside Root**: Localized files reside inside `/docs` (e.g. `docs/README.ar.md`), never linking outside the `/docs` boundary.
+
+---
+
+## 📁 Canonical `/docs` Folder Hierarchy
+
+Every project initialized and maintained by `tidyfactor-doc` strictly adheres to the flattened, no-empty-structures hierarchy:
+
+```
+project-root/
+├── README.md                  # Project overview & quick start (Root)
+└── docs/                      # Single documentation root
+    ├── README.md              # Doc-site landing page & introduction
+    ├── README.ar.md           # Arabic localized overview (optional)
+    ├── index.html             # Docsify single-page application entry point
+    ├── _sidebar.md            # Auto-generated categorized navigation tree
+    ├── .doc-manifest.json     # Machine-readable sync & state manifest
+    ├── .collected/            # Raw interview findings (intermediate artifact)
+    │   ├── core.md
+    │   └── auth-module.md
+    ├── api/                   # Public API & endpoint specifications
+    │   ├── authentication.md
+    │   └── billing.md
+    └── guides/                # Targeted developer & user guides
+        ├── architecture.md
+        ├── developer-setup.md
+        └── deployment-runbook.md
+```
+
+### `.doc-manifest.json` Schema
+```json
+{
+  "project": "my-saas-platform",
+  "stacks": ["php", "ts", "react"],
+  "collected": {
+    "auth": "2026-08-20T14:30:00Z",
+    "core": "2026-08-20T14:32:00Z"
+  },
+  "generated": {
+    "docs/api/auth.md": "2026-08-20T14:35:00Z",
+    "docs/guides/developer-setup.md": "2026-08-20T14:36:00Z",
+    "README.md": "2026-08-20T14:37:00Z"
+  }
+}
+```
+
+---
+
+## 🚀 Quick Start & Injection
+
+### 1. Inject Skill via NPM
+Add `tidyfactor-doc` to your active workspace or global agent registry:
+
+```bash
+npx @tidyfactor/cli-doc add-skill
+```
+
+### 2. Universal Agent Compatibility
+Trigger the skill in your preferred AI Coding Assistant:
+
+| Agent / IDE | Invocation Example |
+|---|---|
+| **Google Antigravity** | `/tidyfactor-doc` or "Document this codebase and build a Docsify site" |
+| **Claude Code** | `/tidyfactor-doc init` or "Generate API docs for src/Core" |
+| **Cursor & Windsurf** | `@tidyfactor-doc Set up /docs and interview this PHP module` |
+| **Codex CLI** | `tidyfactor-doc generate API reference` |
+
+### 3. Local Preview
+Preview your Docsify documentation portal in real time:
+
+```bash
+# Using PHP built-in server
+php -S localhost:3001 -t docs
+
+# Or using Docsify CLI / Python
+npx docsify-cli serve docs
+python -m http.server 3001 -d docs
+```
+
+---
+
+## 👨‍💻 Organization & Support
+
+- 🌐 **Official Website:** [https://tidyfactor.com/](https://tidyfactor.com/)
+- 📚 **Official Documentation:** [https://tidyfactor.com/documentation](https://tidyfactor.com/documentation)
+- 🤝 **Official Partner Website:** [Alwkala Digital Agency](https://alwkala.com/)
+- 🐙 **GitHub Organization:** [github.com/TidyFactor](https://github.com/TidyFactor)
+- 📧 **Business Inquiries:** [hello@tidyfactor.com](mailto:hello@tidyfactor.com)
+- 📱 **WhatsApp:** [+20 101 665 6899](https://wa.me/201016656899)
+- 📞 **Phone:** +20 101 665 6899
+- 📍 **Location:** Cairo, Egypt
+
+---
+
+## 📜 License
+
+Licensed under the **Apache License 2.0**. Copyright (c) 2026 [TidyFactor](https://tidyfactor.com) & [Alwkala](https://alwkala.com).

package/README.pt.md

@@ -0,0 +1,44 @@
+<div align="center">
+
+# tidyfactor-doc `v1.3.0`
+
+**Construtor de Documentação de Código e Motor de Publicação Duplo (MkDocs & Docsify) para Agentes de IA**
+
+[![npm version](https://img.shields.io/npm/v/@tidyfactor/doc.svg?style=for-the-badge&color=0284C7)](https://www.npmjs.com/package/@tidyfactor/doc)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg?style=for-the-badge)](LICENSE)
+
+[ 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)
+
+</div>
+
+---
+
+## ⚡ Início Rápido (Quickstart)
+
+```bash
+# Instalação e execução via NPX
+npx @tidyfactor/cli-doc
+```
+
+Ou execute diretamente dentro do seu assistente de IA (*Google Antigravity, Claude Code, Cursor, Codex*):
+```text
+/tidyfactor-doc
+```
+
+---
+
+## 📋 Matriz de Comandos Principais
+
+| Comando | Objetivo e Resultado | Fluxo de Trabalho |
+|---|---|---|
+| `/init` | Inicialización de estructura de documentación | `workflows/init.md` |
+| `/collect` | Entrevista y análisis de código fuente | `workflows/collect.md` |
+| `/generate` | Generación de especificaciones API y READMEs | `workflows/generate.md` |
+| `/mkdocs` | Compilación de portal estático MkDocs Material | `workflows/mkdocs.md` |
+| `/docsify` | Despliegue de SPA ligera Docsify sin compilación | `workflows/docsify.md` |
+
+---
+
+## 📖 Especificação Técnica Canônica
+
+Para a arquitetura detalhada, esquemas JSON completos e código fonte nativo, consulte a [Documentação Técnica Canônica em Inglês (README.md)](README.md).

package/README.zh.md

@@ -0,0 +1,44 @@
+<div align="center">
+
+# tidyfactor-doc `v1.3.0`
+
+**面向 AI 智能体的代码库文档自动生成与双引擎发布平台 (MkDocs & Docsify)**
+
+[![npm version](https://img.shields.io/npm/v/@tidyfactor/doc.svg?style=for-the-badge&color=0284C7)](https://www.npmjs.com/package/@tidyfactor/doc)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg?style=for-the-badge)](LICENSE)
+
+[ 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)
+
+</div>
+
+---
+
+## ⚡ 快速上手 (Quickstart)
+
+```bash
+# 通过 NPX 快速运行
+npx @tidyfactor/cli-doc
+```
+
+或在 AI 编码助手 (*Google Antigravity, Claude Code, Cursor, Codex*) 中调用：
+```text
+/tidyfactor-doc
+```
+
+---
+
+## 📋 核心命令矩阵
+
+| 命令 | 目标与产出 | 执行工作流 |
+|---|---|---|
+| `/init` | Inicialización de estructura de documentación | `workflows/init.md` |
+| `/collect` | Entrevista y análisis de código fuente | `workflows/collect.md` |
+| `/generate` | Generación de especificaciones API y READMEs | `workflows/generate.md` |
+| `/mkdocs` | Compilación de portal estático MkDocs Material | `workflows/mkdocs.md` |
+| `/docsify` | Despliegue de SPA ligera Docsify sin compilación | `workflows/docsify.md` |
+
+---
+
+## 📖 完整技术规范与文档
+
+如需查看深层架构设计、完整 JSON Schema 契约和原生代码，请参阅[英文权威技术文档 (README.md)](README.md)。

package/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tidyfactor-doc
+description: "Code documentation builder and dual-engine publishing platform (MkDocs Material and Docsify). Generates comprehensive API references, READMEs, inline docblocks, and technical guides under /docs. Trigger on commands 'init', 'collect', 'generate', 'site', 'mkdocs', 'docsify', or requests like 'document this codebase', 'generate API docs', 'set up MkDocs', or 'set up Docsify'."
+---
+# TidyFactor Doc
+
+A command dispatcher. This file does not do the work itself — it routes to the right command, which routes to the right workflow, which injects the right memory.
+
+## Commands
+
+| User intent | Command | What it loads |
+|---|---|---|
+| "Set up docs for this project" / "scaffold /docs" | `references/commands/init.md` | `workflows/init-docs.md` + `memory/doc-tree.md` |
+| "Document this codebase" / "gather what's needed to document X" | `references/commands/collect.md` | `workflows/collect.md` + `memory/collection-sources.md` |
+| "Write API docs" / "generate a README" / "add inline comments" / "write a guide" | `references/commands/generate.md` | `workflows/generate-api.md` (or `generate-readme.md` / `generate-inline.md` / `generate-guide.md`) + `memory/doc-templates.md` + matching `memory/stacks/*.md` |
+| "Publish documentation portal" / "turn /docs into a doc site" (Interactive) | `references/commands/site.md` | `memory/site-engines.md` + interactive selection (`workflows/mkdocs.md` or `workflows/docsify.md`) |
+| "Set up MkDocs Material" / "compile static documentation" | `references/commands/mkdocs.md` | `workflows/mkdocs.md` + `memory/mkdocs-config.md` |
+| "Set up Docsify" / "build lightweight zero-build doc SPA" | `references/commands/docsify.md` | `workflows/docsify.md` + `memory/docsify-config.md` |
+
+Read only the command file that matches the request. Do not read all commands simultaneously.
+
+## Non-negotiable constraints on every command
+
+1. **All generated documentation lives under `/docs`.** Never write API references, guides, or generated READMEs to another location. (`README.md` itself stays at the project root, per convention — everything else generated goes in `/docs`.)
+2. **`generate` never invents content.** It only writes docs from what `collect` gathered (or equivalent detail the user supplies directly in the conversation) — never from assumed signatures, assumed env vars, or assumed behavior. If required detail is missing, `generate` says what's missing and asks or falls back to running `collect` first.
+3. **Stack rules are looked up, never guessed.** Before writing any code-level doc (API reference, inline comments), load the matching file under `memory/stacks/` for the language/framework actually in use. Do not mix PHPDoc conventions into a TypeScript file or vice versa.
+4. **`site`, `mkdocs`, and `docsify` only organize and publish what's already in `/docs`.** They never author new documentation content — that's `generate`'s job.
+   - For **MkDocs Material**: Generate standard `mkdocs.yml`, configure Neo-Brutalist CSS tokens (`extra.css`), configure Arabic/English i18n (`*.ar.md` suffix), and build cleanly with `mkdocs build --strict`.
+   - For **Docsify**: Include `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` and root-relative leading slashes `/` in `_sidebar.md` to guarantee persistent sidebar navigation across all subfolder routes.
+5. **Standalone.** This skill does not read or depend on any other `tidyfactor-*` skill's conventions, even when the project happens to be built on one of those tracks.
+6. **Zero Sensitive Data Leakage.** Under absolutely no circumstances should any real sensitive data (e.g., real API tokens, WHM/cPanel passwords, production server IPs, real DB credentials, secret keys, private auth tokens, or local absolute drive paths) be written into documentation. ALWAYS redact and replace these with safe generic placeholders.
+7. **Clean Relative Links Only.** Never include local machine filesystem URLs (such as `file:///C:/...`, `file:c:`, or absolute workstation paths) in documentation links or markdown cross-references. All document cross-links must use clean relative markdown paths or standard public web URLs (`https://...`).
+
+## Sequencing
+
+`init` → `collect` → `generate` (repeatable, once per doc target) → `site` / `mkdocs` / `docsify` (optional, once /docs has real content).

package/bin/add-skill.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const targetDir = process.cwd();
+const skillSource = path.resolve(__dirname, '..');
+const agentSkillsDir = path.join(targetDir, '.agents', 'skills', 'tidyfactor-doc');
+
+fs.mkdirSync(agentSkillsDir, { recursive: true });
+
+function copyRecursive(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (['.git', 'node_modules', 'bin'].includes(entry.name)) continue;
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+copyRecursive(skillSource, agentSkillsDir);
+console.log('✓ Successfully injected tidyfactor-doc skill into .agents/skills/tidyfactor-doc');

package/brand.json

@@ -0,0 +1,13 @@
+{
+  "name": "TidyFactor Doc",
+  "version": "1.3.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"
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@tidyfactor/doc",
+  "version": "1.3.0",
+  "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
+  "main": "SKILL.md",
+  "bin": {
+    "tidyfactor-doc": "bin/add-skill.js",
+    "add-skill": "bin/add-skill.js",
+    "add-doc-skill": "bin/add-skill.js"
+  },
+  "keywords": [
+    "tidyfactor",
+    "docs",
+    "docsify",
+    "mkdocs",
+    "ai-agents",
+    "antigravity",
+    "claude-code",
+    "cursor",
+    "documentation-generator"
+  ],
+  "author": "TidyFactor <hello@tidyfactor.com> (https://tidyfactor.com)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TidyFactor/Doc.git"
+  },
+  "scripts": {
+    "validate": "python tools/validate_skill.py",
+    "build": "node tools/build-skill.js",
+    "release": "python ../tools/release_skill.py ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".tidyfactor",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.ar.md",
+    "README.de.md",
+    "README.es.md",
+    "README.fa.md",
+    "README.fr.md",
+    "README.md",
+    "README.pt.md",
+    "README.zh.md",
+    "SKILL.md",
+    "assets",
+    "bin",
+    "brand.json",
+    "memory",
+    "references",
+    "scripts",
+    "templates",
+    "tools"
+  ]
+}

package/references/commands/collect.md

@@ -0,0 +1,15 @@
+# Command: collect
+
+Runtime entry point for "document this codebase" / "gather what's needed to document X."
+
+## Dispatch steps
+
+1. Load `../memory/collection-sources.md` — the five collection dimensions and what to extract from each.
+2. Load `../workflows/collect.md` — the ordered interview/extraction sequence.
+3. Run the workflow against the target codebase (or the specific slice of it the user named — a single module, endpoint, or component).
+
+## Does NOT
+
+- Does not write any files under `/docs`. `collect`'s output is structured source material (findings written to `docs/.collected/<target>.md`, per `collect.md`'s own step) — not a finished doc.
+- Does not load `memory/doc-templates.md` or any `memory/stacks/*.md` file — formatting the findings into a stack-correct doc is `generate`'s job, not this one.
+- Does not require `init` to have run first, but if `docs/.doc-manifest.json` doesn't exist yet, say so and offer to run `init` first rather than silently creating an ad hoc structure.

package/references/commands/docsify.md

@@ -0,0 +1,15 @@
+# Command: docsify
+
+Runtime entry point for "turn /docs into a doc site" / "set up Docsify (Zero-Build SPA)."
+
+## Dispatch steps
+
+1. Load `../memory/docsify-config.md` — file layout, plugin defaults, sidebar-generation rule, deploy targets.
+2. Load `../workflows/docsify.md` — the setup sequence.
+3. Confirm `/docs` already has real content (at least one generated doc beyond the scaffold).
+4. Run `workflows/docsify.md`.
+
+## Does NOT
+
+- Does not author any new page content — it wires up navigation (`_sidebar.md`), an entry point (`index.html`), and optionally a cover page over whatever already exists in `/docs`.
+- Does not load `memory/doc-templates.md` or any `memory/stacks/*.md` file.

package/references/commands/generate.md

@@ -0,0 +1,23 @@
+# Command: generate
+
+Runtime entry point for "write API docs" / "generate a README" / "add inline comments" / "write a guide." A router within a router: figure out which doc type is wanted, then load exactly one workflow for it.
+
+## Dispatch steps
+
+1. **Identify the doc type.** If not obvious from the request, ask:
+   > "Which one — API reference, README, inline code comments, or a technical guide (setup/architecture/workflow)?"
+2. **Identify the stack** (PHP / JS / TS / React / Vue / Next). If not obvious from the project, ask or detect from file extensions / config files (`composer.json`, `package.json` + `tsconfig.json`, framework config files).
+3. Load the matching workflow — exactly one:
+   - API reference → `../workflows/generate-api.md`
+   - README → `../workflows/generate-readme.md`
+   - Inline comments → `../workflows/generate-inline.md`
+   - Guide → `../workflows/generate-guide.md`
+4. Load `../memory/doc-templates.md`.
+5. Load the matching stack file under `../memory/stacks/` — `php.md`, `js-ts.md`, or `react-vue-next.md`. Never load more than the stacks actually present in the target.
+6. Confirm `collect` has already run for this target (check for `docs/.collected/<target>.md`). If it hasn't, and the user hasn't supplied equivalent detail inline, stop and say so — do not generate from assumption. See constraint 2 in `SKILL.md`.
+7. Run the loaded workflow.
+
+## Does NOT
+
+- Does not load more than one `workflows/generate-*.md` file per invocation. Multiple doc types requested at once → run this dispatch sequence once per type, sequentially.
+- Does not load `memory/collection-sources.md` or `memory/docsify-config.md` — not this command's concern.

package/references/commands/init.md

@@ -0,0 +1,15 @@
+# Command: init
+
+Runtime entry point for "set up docs for this project" / "scaffold /docs."
+
+## Dispatch steps
+
+1. Load `../memory/doc-tree.md` — the canonical `/docs` folder shape and the doc-manifest schema.
+2. Load `../workflows/init-docs.md` — the scaffolding sequence.
+3. Run the workflow.
+
+## Does NOT
+
+- Does not write any actual documentation content (no API entries, no guide prose). That's `generate`.
+- Does not run `collect`. If the user wants both, run `init` first, then hand off to `collect`.
+- Does not load any `memory/stacks/*.md` file — stack detection here only decides which manifest fields to pre-fill, not how to document anything yet.

package/references/commands/mkdocs.md

@@ -0,0 +1,15 @@
+# Command: mkdocs
+
+Runtime entry point for "set up MkDocs" / "build MkDocs Material site" / "compile static documentation".
+
+## Dispatch steps
+
+1. Load `../memory/mkdocs-config.md` — master YAML schema, theme tokens, extensions, i18n rules, and deploy options.
+2. Load `../workflows/mkdocs.md` — the setup and build sequence.
+3. Confirm `/docs` has real content.
+4. Run `workflows/mkdocs.md`.
+
+## Does NOT
+
+- Does not author new documentation content — it generates `mkdocs.yml`, configures themes, and compiles the static site.
+- Does not modify source markdown semantics, only removes incompatible raw HTML wrappers.

package/references/commands/site.md

@@ -0,0 +1,23 @@
+# Command: site
+
+Runtime entry point for "turn /docs into a doc site" / "publish documentation portal" / "set up documentation site".
+
+## Dispatch steps
+
+1. Load `../memory/site-engines.md` — comparison between MkDocs Material and Docsify.
+2. Confirm `/docs` has real content (at least one generated doc beyond the scaffold).
+3. **Interactive Engine Selection:**
+   - Detect if Python is available via `python --version 2>&1`.
+   - If the user explicitly requested a specific engine (e.g., "use mkdocs" or "use docsify"), route directly:
+     - "mkdocs" → Dispatch `references/commands/mkdocs.md`.
+     - "docsify" → Dispatch `references/commands/docsify.md`.
+   - If no engine was specified:
+     - Present the two options to the user with the summary from `memory/site-engines.md`:
+       - **Option 1: MkDocs Material (Recommended for Production)**: Pre-compiled static HTML, 100/100 Core Web Vitals, bilingual (Arabic RTL + English LTR) parallel builds, offline search indexing, and Neo-Brutalist styling. Requires Python locally for building.
+       - **Option 2: Docsify (Zero-Build Lightweight SPA)**: Client-side SPA, zero build step, single `index.html` + `_sidebar.md` over CDN. Recommended when Python is not available or for internal repo prototyping.
+     - Prompt the user to pick their preference or proceed with the recommended engine based on detected toolchain.
+4. Execute the chosen workflow (`workflows/mkdocs.md` or `workflows/docsify.md`).
+
+## Does NOT
+
+- Does not author any new markdown content — it structures, configures, and publishes what's already in `/docs`.

package/references/memory/collection-sources.md

@@ -0,0 +1,47 @@
+# Memory: collection-sources
+
+The five dimensions `collect` runs against a target, and exactly what to pull from each. Operational — no rationale.
+
+## 1. Code parsing
+
+- Extract existing docblocks/comments verbatim (don't paraphrase yet — that's `generate`'s job).
+- List every public function, method, class, exported type, and (for components) prop/slot/event definition.
+- Note which of these already have adequate comments vs. none vs. stale (comment doesn't match current signature).
+
+## 2. Commit history
+
+- `git log --follow -- <path>` for the target's files: pull commit messages that explain *why*, not routine messages ("fix typo").
+- Any available PR/MR descriptions touching the target: design decisions, rejected alternatives, known limitations mentioned by the author.
+- Flag any TODO/FIXME/HACK comments found alongside — they're often undocumented known issues.
+
+## 3. Runtime & environment
+
+- Every environment variable the target reads (grep for `getenv`/`process.env`/`$_ENV`/config-loader calls), with whether it's required or optional and any default.
+- Software dependencies and version constraints from the manifest (`composer.json`, `package.json`) that the target actually uses — not the whole project's dependency list.
+- Any stated hardware/resource limits (memory limits, timeout values, rate limits) found in config or comments.
+- **Sanitization Rule**: Never collect real values of secrets (API keys, passwords, JWT secrets, private IP addresses, database credentials). Store only the variable name, description, and a synthetic example placeholder (e.g. `sk_test_EXAMPLE123456`, `203.0.113.10`).
+
+## 4. User persona tracing
+
+- Classify the target's readership: **API consumer** (calls it from outside), **internal maintainer** (edits this code), **end-user** (uses a UI built on it), or a mix.
+- For each persona present, note which facts from the other four dimensions matter to them — this list is what `generate` uses to prioritize content per doc type.
+
+## 5. Error patterns
+
+- Every thrown exception / returned error code / rejected promise in the target, with the condition that triggers it.
+- How each error is meant to be handled or surfaced (caught and logged? bubbled to caller? shown to end-user?) — from code and any logging statements found.
+- Common failure modes mentioned in commit history or TODO comments that aren't yet reflected in actual error handling.
+- **Scrubbing Rule**: Redact real database connection strings, local absolute file paths (e.g. `/home/user/project/...`), or authorization headers that might appear in error logs or exception messages.
+
+---
+
+## 🔒 Security & Link Sanitization Reference
+
+| Item Category | Dangerous / Prohibited | Mandatory Safe Replacement |
+|---|---|---|
+| API Keys / Tokens | `sk_live_948f98a7c...` | `YOUR_API_KEY_HERE` or `EXAMPLE_TOKEN_123` |
+| Passwords / DB Secrets | `P@ssw0rd2026!` | `your_secure_password` |
+| Server IPs | `192.168.1.15`, `45.33.21.99` | `203.0.113.1` (RFC 5737 doc range) |
+| Local Drive Paths | `file:///C:/path/to/project/...` | `./docs/guides/` or `project-root/` |
+| Local Workstation URLs | `http://localhost:8080/secret` | `https://api.example.com` or `http://localhost:PORT` |
+| User Home Dirs | `/home/developer/workspace/...` | `~/project` or `/path/to/project` |