@tidyfactor/doc 1.3.0 → 1.9.0

package/references/memory/mkdocs-config.md

@@ -1,170 +1,171 @@
-# Memory: MkDocs Material Configuration Spec
-
-Complete architectural specification for scaffolding and compiling production-grade documentation portals with MkDocs Material.
-
----
-
-## 1. Package Requirements (`requirements.txt`)
-
-```text
-mkdocs-material>=9.5
-mkdocs-static-i18n>=1.2
-```
-
----
-
-## 2. Master Configuration Schema (`mkdocs.yml`)
-
-```yaml
-site_name: Project Documentation
-site_url: https://example.com/docs/
-site_description: "Production Documentation Portal"
-site_author: Engineering Team
-
-docs_dir: docs
-site_dir: site
-
-theme:
-  name: material
-  language: en
-  direction: ltr
-  custom_dir: overrides
-
-  logo: assets/logo.png
-  favicon: assets/favicon.png
-
-  font:
-    text: Plus Jakarta Sans
-    code: Fira Code
-
-  palette:
-    # Light Mode
-    - media: "(prefers-color-scheme: light)"
-      scheme: tidyfactor-light
-      primary: custom
-      accent: custom
-      toggle:
-        icon: material/brightness-7
-        name: Switch to Dark Mode
-
-    # Dark Mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: tidyfactor-dark
-      primary: custom
-      accent: custom
-      toggle:
-        icon: material/brightness-4
-        name: Switch to Light Mode
-
-  features:
-    - navigation.tracking
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.sections
-    - navigation.expand
-    - navigation.path
-    - navigation.top
-    - navigation.indexes
-    - navigation.footer
-    - search.suggest
-    - search.highlight
-    - search.share
-    - content.code.copy
-    - content.code.annotate
-    - content.tabs.link
-    - header.autohide
-    - toc.follow
-
-plugins:
-  - search:
-      separator: '[\s\-\.]+'
-      lang:
-        - en
-        - ar
-
-  - i18n:
-      docs_structure: suffix
-      languages:
-        - locale: en
-          name: English
-          default: true
-          build: true
-        - locale: ar
-          name: العربية
-          build: true
-          theme:
-            language: ar
-            direction: rtl
-            font:
-              text: Tajawal
-              code: Fira Code
-
-markdown_extensions:
-  - abbr
-  - admonition
-  - attr_list
-  - def_list
-  - footnotes
-  - md_in_html
-  - tables
-  - toc:
-      permalink: true
-      toc_depth: 3
-  - pymdownx.arithmatex:
-      generic: true
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.details
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.keys
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-
-extra_css:
-  - stylesheets/extra.css
-
-extra_javascript:
-  - javascripts/extra.js
-```
-
----
-
-## 3. Bilingual Suffix Rule (i18n)
-
-- English source files: `docs/guides/architecture.md`, `docs/index.md`
-- Arabic source files: `docs/guides/architecture.ar.md`, `docs/index.ar.md`
-- Rule: Never link directly to `.ar.md` from `.md` files; the `i18n` plugin handles language linking automatically via the header switcher.
-
----
-
-## 4. Local Apache Subfolder Routing (`.htaccess`)
-
-When hosting the documentation inside a subfolder during local Apache/WAMP development:
-
-```apache
-<IfModule mod_rewrite.c>
-    RewriteEngine On
-    RewriteRule ^site(/.*)?$ - [L]
-    RewriteCond %{REQUEST_FILENAME} !-f
-    RewriteRule ^(.*)$ site/$1 [L]
-</IfModule>
-```
-In production: upload the contents of `site/` directly into `public_html/docs/`.
+<!-- last-verified: 2026-09-02 -->
+# Memory: MkDocs Material Configuration Spec
+
+Complete architectural specification for scaffolding and compiling production-grade documentation portals with MkDocs Material.
+
+---
+
+## 1. Package Requirements (`requirements.txt`)
+
+```text
+mkdocs-material>=9.5
+mkdocs-static-i18n>=1.2
+```
+
+---
+
+## 2. Master Configuration Schema (`mkdocs.yml`)
+
+```yaml
+site_name: Project Documentation
+site_url: https://example.com/docs/
+site_description: "Production Documentation Portal"
+site_author: Engineering Team
+
+docs_dir: docs
+site_dir: site
+
+theme:
+  name: material
+  language: en
+  direction: ltr
+  custom_dir: overrides
+
+  logo: assets/logo.png
+  favicon: assets/favicon.png
+
+  font:
+    text: Plus Jakarta Sans
+    code: Fira Code
+
+  palette:
+    # Light Mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: tidyfactor-light
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to Dark Mode
+
+    # Dark Mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: tidyfactor-dark
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to Light Mode
+
+  features:
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - navigation.indexes
+    - navigation.footer
+    - search.suggest
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - header.autohide
+    - toc.follow
+
+plugins:
+  - search:
+      separator: '[\s\-\.]+'
+      lang:
+        - en
+        - ar
+
+  - i18n:
+      docs_structure: suffix
+      languages:
+        - locale: en
+          name: English
+          default: true
+          build: true
+        - locale: ar
+          name: العربية
+          build: true
+          theme:
+            language: ar
+            direction: rtl
+            font:
+              text: Tajawal
+              code: Fira Code
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      toc_depth: 3
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/extra.js
+```
+
+---
+
+## 3. Bilingual Suffix Rule (i18n)
+
+- English source files: `docs/guides/architecture.md`, `docs/index.md`
+- Arabic source files: `docs/guides/architecture.ar.md`, `docs/index.ar.md`
+- Rule: Never link directly to `.ar.md` from `.md` files; the `i18n` plugin handles language linking automatically via the header switcher.
+
+---
+
+## 4. Local Apache Subfolder Routing (`.htaccess`)
+
+When hosting the documentation inside a subfolder during local Apache/WAMP development:
+
+```apache
+<IfModule mod_rewrite.c>
+    RewriteEngine On
+    RewriteRule ^site(/.*)?$ - [L]
+    RewriteCond %{REQUEST_FILENAME} !-f
+    RewriteRule ^(.*)$ site/$1 [L]
+</IfModule>
+```
+In production: upload the contents of `site/` directly into `public_html/docs/`.

package/references/memory/naming-conventions.md

@@ -0,0 +1,40 @@
+<!-- last-verified: 2026-09-09 -->
+# 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<T>`, `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`).

package/references/memory/project-mindmap.md

@@ -0,0 +1,66 @@
+<!-- last-verified: 2026-09-09 -->
+# 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.

package/references/memory/site-engines.md

@@ -1,54 +1,52 @@
-# Memory: Site Engines (Docsify vs. MkDocs Material)
+<!-- last-verified: 2026-09-09 -->
+# 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.

package/references/memory/stacks/js-ts.md

@@ -1,45 +1,47 @@
-# Memory: stacks/js-ts
-
-Documentation conventions for JavaScript and TypeScript targets. Applies whenever the target's manifest is `package.json` and files are `.js`/`.mjs` (JS) or `.ts`/`.tsx` (TS). The two share JSDoc-style block syntax but differ in what needs restating.
-
-## JavaScript — JSDoc (types belong in the comment, since the code itself is untyped)
-
-```js
-/**
- * <one-line summary>
- *
- * @param {string} name Description.
- * @param {number} [limit] Optional, defaults to undefined.
- * @returns {Promise<object>} Description of the resolved shape.
- * @throws {RangeError} When <condition, from error-patterns findings>.
- */
-```
-
-- Always include `@param`/`@returns` types — JS has no compile-time types, so the comment is the only source of truth.
-- Optional params use `[name]` bracket syntax.
-
-## TypeScript — TSDoc (types live in the signature, don't restate them in the comment)
-
-```ts
-/**
- * <one-line summary>
- *
- * @param name - Description only, no type (already in the signature).
- * @param limit - Description only.
- * @returns Description only.
- * @throws {RangeError} When <condition, from error-patterns findings>.
- */
-function example(name: string, limit?: number): Promise<Result> { ... }
-```
-
-- Do NOT restate types already visible in the TS signature (`{string}`, `{number}`) — that's a JSDoc habit that's redundant and can drift out of sync in TS. Description only after the `-`.
-- Exported `interface`/`type` declarations get their own TSDoc block above the declaration, one line per member if the member itself isn't self-explanatory.
-
-## API reference formatting
-
-- Show the actual signature from the source (JS: as written; TS: full typed signature).
-- For TS, prefer documenting the public exported types directly rather than re-describing them in prose.
-
-## What NOT to document inline
-
-- Non-exported (module-private) helper functions with obvious names: skip full blocks unless the error-patterns findings show them as a common failure point.
+# Memory: stacks/js-ts
+
+<!-- last-verified: 2026-09-08 -->
+
+Documentation conventions for JavaScript and TypeScript targets. Applies whenever the target's manifest is `package.json` and files are `.js`/`.mjs` (JS) or `.ts`/`.tsx` (TS). The two share JSDoc-style block syntax but differ in what needs restating.
+
+## JavaScript — JSDoc (types belong in the comment, since the code itself is untyped)
+
+```js
+/**
+ * <one-line summary>
+ *
+ * @param {string} name Description.
+ * @param {number} [limit] Optional, defaults to undefined.
+ * @returns {Promise<object>} Description of the resolved shape.
+ * @throws {RangeError} When <condition, from error-patterns findings>.
+ */
+```
+
+- Always include `@param`/`@returns` types — JS has no compile-time types, so the comment is the only source of truth.
+- Optional params use `[name]` bracket syntax.
+
+## TypeScript — TSDoc (types live in the signature, don't restate them in the comment)
+
+```ts
+/**
+ * <one-line summary>
+ *
+ * @param name - Description only, no type (already in the signature).
+ * @param limit - Description only.
+ * @returns Description only.
+ * @throws {RangeError} When <condition, from error-patterns findings>.
+ */
+function example(name: string, limit?: number): Promise<Result> { ... }
+```
+
+- Do NOT restate types already visible in the TS signature (`{string}`, `{number}`) — that's a JSDoc habit that's redundant and can drift out of sync in TS. Description only after the `-`.
+- Exported `interface`/`type` declarations get their own TSDoc block above the declaration, one line per member if the member itself isn't self-explanatory.
+
+## API reference formatting
+
+- Show the actual signature from the source (JS: as written; TS: full typed signature).
+- For TS, prefer documenting the public exported types directly rather than re-describing them in prose.
+
+## What NOT to document inline
+
+- Non-exported (module-private) helper functions with obvious names: skip full blocks unless the error-patterns findings show them as a common failure point.