@tidyfactor/doc 1.3.0 → 1.9.0

package/references/memory/stacks/php.md

@@ -1,33 +1,35 @@
-# Memory: stacks/php
-
-Documentation conventions for PHP targets. Applies whenever the target's manifest is `composer.json` or files are `.php`.
-
-## Inline comment format — PHPDoc
-
-```php
-/**
- * <one-line summary>
- *
- * <optional longer description>
- *
- * @param string $name Description of the parameter.
- * @param int|null $limit Description. Optional, defaults to null.
- * @return array<string, mixed> Description of the return shape.
- * @throws InvalidArgumentException When <condition, from error-patterns findings>.
- */
-```
-
-- One blank-line-separated summary + description, then tags.
-- Always type-hint `@param`/`@return` even when the function itself is already typed — PHPDoc types can be more specific (e.g. `array<string, int>` vs. plain `array`).
-- `@throws` is mandatory whenever the error-patterns findings show this function throwing — never omit it to save space.
-- Class-level docblocks get `@package` only if the project already uses PSR-4 namespacing conventions that make it meaningful; skip otherwise.
-
-## API reference formatting
-
-- Signatures shown as the actual PHP declaration line (with type hints), not a paraphrase: `public function createUser(string $email, ?int $roleId = null): User`
-- Nullable/union types shown exactly as declared (`?int`, `int|string`).
-- Static vs. instance methods both documented the same way — note staticness in the signature itself, not as prose.
-
-## What NOT to document inline
-
-- Private/protected helper methods with obvious single-purpose names don't need a full docblock — a one-line `// ` comment is enough, or none if truly self-evident. Full PHPDoc blocks are for the public API surface.
+# Memory: stacks/php
+
+<!-- last-verified: 2026-09-08 -->
+
+Documentation conventions for PHP targets. Applies whenever the target's manifest is `composer.json` or files are `.php`.
+
+## Inline comment format — PHPDoc
+
+```php
+/**
+ * <one-line summary>
+ *
+ * <optional longer description>
+ *
+ * @param string $name Description of the parameter.
+ * @param int|null $limit Description. Optional, defaults to null.
+ * @return array<string, mixed> Description of the return shape.
+ * @throws InvalidArgumentException When <condition, from error-patterns findings>.
+ */
+```
+
+- One blank-line-separated summary + description, then tags.
+- Always type-hint `@param`/`@return` even when the function itself is already typed — PHPDoc types can be more specific (e.g. `array<string, int>` vs. plain `array`).
+- `@throws` is mandatory whenever the error-patterns findings show this function throwing — never omit it to save space.
+- Class-level docblocks get `@package` only if the project already uses PSR-4 namespacing conventions that make it meaningful; skip otherwise.
+
+## API reference formatting
+
+- Signatures shown as the actual PHP declaration line (with type hints), not a paraphrase: `public function createUser(string $email, ?int $roleId = null): User`
+- Nullable/union types shown exactly as declared (`?int`, `int|string`).
+- Static vs. instance methods both documented the same way — note staticness in the signature itself, not as prose.
+
+## What NOT to document inline
+
+- Private/protected helper methods with obvious single-purpose names don't need a full docblock — a one-line `// ` comment is enough, or none if truly self-evident. Full PHPDoc blocks are for the public API surface.

package/references/memory/stacks/react-vue-next.md

@@ -1,50 +1,52 @@
-# Memory: stacks/react-vue-next
-
-Component-level documentation conventions, layered on top of `js-ts.md` (still use JSDoc/TSDoc block syntax — this file adds what's specific to components, pages, and routes).
-
-## React — props, not just function signature
-
-```tsx
-/**
- * <one-line summary of what the component renders/does>
- */
-interface ButtonProps {
-  /** Description of this prop. */
-  label: string;
-  /** Optional, defaults to 'primary'. */
-  variant?: 'primary' | 'secondary';
-  /** Called when clicked. */
-  onClick?: () => void;
-}
-```
-
-- Document props via the `interface`/`type` block (per-member comments), not a `@param` list on the component function — that's the idiomatic React pattern and what most tooling (Storybook, TypeDoc) expects.
-- Note default values from the actual destructured defaults or `defaultProps`, not assumed.
-
-## Vue — SFC `<script>` block comments + `defineProps`
-
-```vue
-<script setup lang="ts">
-/**
- * <one-line summary>
- */
-defineProps<{
-  /** Description. */
-  label: string;
-  /** Optional, defaults to 'primary'. */
-  variant?: 'primary' | 'secondary';
-}>();
-</script>
-```
-
-- For Options API components (no `<script setup>`), document each prop inside the `props: {}` object with a comment above it instead.
-- Emitted events (`defineEmits` / `this.$emit`) get documented the same way props do — name, payload type, when it fires (from code parsing + error-patterns findings if it's an error event).
-
-## Next.js — pages/routes get a route-level note, not just a component doc
-
-- For a page/route file, prepend a comment noting the route path, whether it's a Server or Client Component, and any `params`/`searchParams` it reads — this is route contract, not just component contract.
-- API routes (`route.ts`/`route.js` under `app/api/`, or `pages/api/`) are documented as API reference (`generate-api`, using `js-ts.md`'s function conventions for the handler), not as component docs.
-
-## What NOT to document
-
-- Purely presentational/internal sub-components not exported from the module's public entry point: skip the full prop-table treatment unless they're complex enough that the error-patterns or persona-tracing findings flagged them as maintainer-relevant.
+# Memory: stacks/react-vue-next
+
+<!-- last-verified: 2026-09-08 -->
+
+Component-level documentation conventions, layered on top of `js-ts.md` (still use JSDoc/TSDoc block syntax — this file adds what's specific to components, pages, and routes).
+
+## React — props, not just function signature
+
+```tsx
+/**
+ * <one-line summary of what the component renders/does>
+ */
+interface ButtonProps {
+  /** Description of this prop. */
+  label: string;
+  /** Optional, defaults to 'primary'. */
+  variant?: 'primary' | 'secondary';
+  /** Called when clicked. */
+  onClick?: () => void;
+}
+```
+
+- Document props via the `interface`/`type` block (per-member comments), not a `@param` list on the component function — that's the idiomatic React pattern and what most tooling (Storybook, TypeDoc) expects.
+- Note default values from the actual destructured defaults or `defaultProps`, not assumed.
+
+## Vue — SFC `<script>` block comments + `defineProps`
+
+```vue
+<script setup lang="ts">
+/**
+ * <one-line summary>
+ */
+defineProps<{
+  /** Description. */
+  label: string;
+  /** Optional, defaults to 'primary'. */
+  variant?: 'primary' | 'secondary';
+}>();
+</script>
+```
+
+- For Options API components (no `<script setup>`), document each prop inside the `props: {}` object with a comment above it instead.
+- Emitted events (`defineEmits` / `this.$emit`) get documented the same way props do — name, payload type, when it fires (from code parsing + error-patterns findings if it's an error event).
+
+## Next.js — pages/routes get a route-level note, not just a component doc
+
+- For a page/route file, prepend a comment noting the route path, whether it's a Server or Client Component, and any `params`/`searchParams` it reads — this is route contract, not just component contract.
+- API routes (`route.ts`/`route.js` under `app/api/`, or `pages/api/`) are documented as API reference (`generate-api`, using `js-ts.md`'s function conventions for the handler), not as component docs.
+
+## What NOT to document
+
+- Purely presentational/internal sub-components not exported from the module's public entry point: skip the full prop-table treatment unless they're complex enough that the error-patterns or persona-tracing findings flagged them as maintainer-relevant.

package/references/memory/tone-of-voice.md

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

package/references/memory/vitepress-config.md

@@ -0,0 +1,174 @@
+<!-- last-verified: 2026-09-09 -->
+# 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
+## 🧭 جدول المحتويات والمسارات السريعة
+
+<div class="quick-nav-grid">
+
+| 🚀 البدء والأدوات | 💼 التطبيقات وحزم العمل | 🏛️ المعمارية العميقة |
+|---|---|---|
+| • [دليل التثبيت](/guide/getting-started.ar)<br>• [مرجع الطرفية](/tools/cli.ar) | • [تطبيقات الإنتاجية](/apps/productivity.ar)<br>• [حزمة الأعمال](/apps/office-suite.ar) | • [بنية الذاكرة](/architecture/memory-and-search.ar)<br>• [المواصفات الفنية](/specs/architecture_spec.ar) |
+
+</div>
+```

package/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

package/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

package/references/workflows/collect.md

@@ -1,25 +1,60 @@
-# Workflow: collect
-
-One outcome: a structured findings file — `docs/.collected/<target>.md` — that `generate` can turn into any doc type without re-deriving facts from the codebase itself. `<target>` is the module, package, API surface, or component named by the request (or the whole project if none was named).
-
-## Steps
-
-Run all five collection dimensions from `memory/collection-sources.md` against the target. Skip a dimension only if it genuinely doesn't apply (e.g., no Git history available for an uploaded snapshot) — note the skip and why, don't silently omit it.
-
-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 so `generate` doesn't duplicate it.
-2. **Commit history.** Read `git log` and any available PR descriptions for the target's files. Pull out *why* behind non-obvious code — rationale, past bugs fixed, deliberate tradeoffs — not just *what* changed.
-3. **Runtime & environment.** Enumerate required environment variables, config files, software dependencies (with version constraints), and any stated hardware/resource limits. **MANDATORY**: Scrub and redact any actual secrets, production server IPs, database passwords, or private API tokens found in `.env` or config files—record only variable names, expected formats, and generic placeholder values.
-4. **User persona tracing.** Identify who actually reads docs for this target — API consumers, internal maintainers, end-users — and note which facts matter to which persona (an internal maintainer needs the "why"; an API consumer needs the contract).
-5. **Error patterns.** Collect how the code fails: thrown exceptions, error codes, logged failure messages, and how each is meant to be handled or surfaced. Scrub any sensitive runtime credentials or local workstation paths that appear inside logged messages.
-
-6. **Write the findings** to `docs/.collected/<target>.md` as plain structured notes under five headings matching the dimensions above — this is source material for `generate`, not a finished doc, so skip prose polish.
-7. **Update `docs/.doc-manifest.json`**: add `<target>` to the `collected` section with a timestamp.
-
-## Validation checklist
-
-- [ ] `docs/.collected/<target>.md` exists and has content (or an explicit "not applicable" note) under all five dimension headings
-- [ ] Every fact traces to something actually found in the code, history, config, or logs — nothing inferred or assumed
-- [ ] Zero sensitive data leaked: all real API keys, passwords, private IPs, and secrets are replaced with safe generic placeholders
-- [ ] No local workstation drive paths (`C:\...`, `file:///...`) exist in findings; all paths are normalized to project-relative paths
-- [ ] `docs/.doc-manifest.json`'s `collected` section includes `<target>`
-- [ ] Findings are organized by dimension, not pre-formatted as any particular doc type
+# Workflow: collect
+
+One outcome: a structured findings file — `docs/.collected/<target>.md` — that `generate` can turn into any doc type without re-deriving facts from the codebase itself. `<target>` is the module, package, API surface, or component named by the request (or the whole project if none was named).
+
+---
+
+## 📋 Step 0: Context Delta Resolution & Auto-Sensing
+
+Before prompting the user for scope or parameters, execute the mechanical resolution formula:
+
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+
+1. **Auto-Sensing on Disk**:
+   - Inspect `mkdocs.yml`, `docs/index.html`, `docs/.doc-manifest.json`, and codebase structure.
+   - For sources marked with `track_staleness: true`, compare hash/mtime against stored snapshot.
+   - Any parameter resolved from disk is removed from $\text{Unknowns}$.
+
+2. **Fail-Open Brain MCP Acceleration**:
+   - Check if architecture KIs exist via `search_knowledge_base(query="architecture routes apis", scope="project")`.
+   - If Brain MCP is absent, offline, or returns empty, proceed with 0ms delay directly to Step 1 without warnings.
+
+---
+
+## 🔍 Step 1: Codebase Collection Dimensions
+
+Run all five collection dimensions from `memory/collection-sources.md` against the target:
+
+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.
+5. **Error patterns**: Collect how the code fails: thrown exceptions, error codes, logged failure messages, and resolution steps. Scrub local workstation paths.
+
+---
+
+## 💾 Step 2: Persist Findings & Outbound Push
+
+1. Write structured notes to `docs/.collected/<target>.md` under five headings matching the dimensions above.
+2. Update `docs/.doc-manifest.json` with `<target>` and timestamp.
+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
+
+- [ ] Context Delta Resolution executed before prompting user.
+- [ ] `docs/.collected/<target>.md` exists and has content under all five dimension headings.
+- [ ] Every fact traces to verified code, history, config, or logs — zero hallucination.
+- [ ] Zero sensitive data leaked: all real API keys, passwords, private IPs, and secrets replaced with generic placeholders.
+- [ ] No local workstation drive paths (`C:\...`, `file:///...`) exist; all paths are normalized to project-relative paths.
+- [ ] Deterministic audit passed via `python scripts/audit_docs.py docs/.collected/<target>.md`.
+- [ ] `docs/.doc-manifest.json`'s `collected` section includes `<target>`.
+- [ ] Findings organized by dimension, not pre-formatted as any particular doc type.