npm - @tidyfactor/doc - Versions diffs - 1.3.0 - Mend

@tidyfactor/doc 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

package/.tidyfactor +16 -0
package/AGENTS.md +10 -0
package/CHANGELOG.md +75 -0
package/LICENSE +17 -0
package/README.ar.md +180 -0
package/README.de.md +44 -0
package/README.es.md +44 -0
package/README.fa.md +44 -0
package/README.fr.md +44 -0
package/README.md +198 -0
package/README.pt.md +44 -0
package/README.zh.md +44 -0
package/SKILL.md +36 -0
package/assets/hero-banner.png +0 -0
package/assets/og-default.png +0 -0
package/bin/add-skill.js +27 -0
package/brand.json +13 -0
package/package.json +59 -0
package/references/commands/collect.md +15 -0
package/references/commands/docsify.md +15 -0
package/references/commands/generate.md +23 -0
package/references/commands/init.md +15 -0
package/references/commands/mkdocs.md +15 -0
package/references/commands/site.md +23 -0
package/references/memory/collection-sources.md +47 -0
package/references/memory/doc-templates.md +73 -0
package/references/memory/doc-tree.md +37 -0
package/references/memory/docsify-config.md +273 -0
package/references/memory/mkdocs-config.md +170 -0
package/references/memory/site-engines.md +54 -0
package/references/memory/stacks/js-ts.md +45 -0
package/references/memory/stacks/php.md +33 -0
package/references/memory/stacks/react-vue-next.md +50 -0
package/references/workflows/collect.md +25 -0
package/references/workflows/docsify.md +19 -0
package/references/workflows/generate-api.md +21 -0
package/references/workflows/generate-guide.md +20 -0
package/references/workflows/generate-inline.md +20 -0
package/references/workflows/generate-readme.md +20 -0
package/references/workflows/init-docs.md +18 -0
package/references/workflows/mkdocs.md +44 -0
package/tools/build-skill.js +152 -0
package/tools/validate_skill.py +124 -0

package/references/memory/doc-templates.md ADDED Viewed

@@ -0,0 +1,73 @@
+# Memory: doc-templates
+Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings.
+## API reference (`docs/api/<target>.md`)
+```markdown
+# <Target> API Reference
+<one-line purpose, from code parsing findings>
+## <FunctionOrMethodName>
+<signature, stack-formatted per the matching stacks/*.md file>
+**Parameters**
+| Name | Type | Required | Description |
+|---|---|---|---|
+**Returns**: <type> — <description>
+**Throws / Errors**: <from error-patterns findings>
+**Example**
+<minimal usage example>
+---
+<!-- repeat per public function/method/endpoint/component -->
+## See also
+<cross-links to related target docs, if any>
+```
+## README (project root `README.md`)
+```markdown
+# <Project Name>
+<one-line description>
+## Requirements
+<software dependencies + version constraints, from runtime & environment findings>
+## Setup
+<install steps, from runtime & environment findings>
+## Environment variables
+| Variable | Required | Default | Description | Example |
+|---|---|---|---|---|
+| `API_KEY` | Yes | — | Secret authentication token | `EXAMPLE_TOKEN_1234567890ABCDEFGH` |
+| `DB_HOST` | Yes | `localhost` | Database host IP or hostname | `203.0.113.10` |
+| `DB_PASS` | Yes | — | Database user password | `your_secret_password` |
+## Usage
+<minimal example>
+## Documentation
+Full reference: [`/docs`](./docs/README.md)
+```
+## Guide (`docs/guides/<purpose-slug>.md`)
+```markdown
+# <Guide Title>
+<one-line: what this guide covers and who it's for, from persona-tracing findings>
+## <Section per logical step or concept>
+<content, prioritized for the target persona>
+## Related
+<links to other guides or API docs using relative paths, e.g. [API Overview](../api/project.md)>
+```

package/references/memory/doc-tree.md ADDED Viewed

@@ -0,0 +1,37 @@
+# Memory: doc-tree
+Canonical `/docs` folder shape and the manifest schema. Every command reads this before touching `/docs` so the structure stays identical across projects.
+## Folder shape
+```
+docs/
+├── README.md              # doc-site landing page (generated by init)
+├── .doc-manifest.json      # tracking file (generated by init, updated by collect/generate)
+├── .collected/              # raw findings from `collect`, one file per target — not site content
+│   └── <target>.md
+├── api/                     # one file per documented target — only if the project has an API surface
+│   └── <target>.md
+└── guides/                  # one file per guide purpose — only once at least one guide exists
+    └── <purpose-slug>.md
+```
+No Empty Structures: `init` creates `api/` only if the stack detection found an API surface (endpoints, public package exports), and `guides/` is created lazily by the first `generate-guide` run, not by `init`. `.collected/` is created lazily by the first `collect` run.
+## `.doc-manifest.json` schema
+```json
+{
+  "project": "<name from composer.json/package.json>",
+  "stacks": ["php" | "js" | "ts" | "react" | "vue" | "next", "..."],
+  "collected": {
+    "<target>": "<ISO timestamp of last collect run>"
+  },
+  "generated": {
+    "<path relative to project root>": "<ISO timestamp of last generate run>"
+  }
+}
+```
+- `collected` and `generated` are separate: a target can be collected without anything generated from it yet.
+- `generated` entries aren't limited to `/docs` paths — `generate-readme` writes to root `README.md` and `generate-inline` touches source files, both still tracked here for audit purposes.

package/references/memory/docsify-config.md ADDED Viewed

@@ -0,0 +1,273 @@
+# Memory: docsify-config
+Fixed Docsify setup used by the `docsify` workflow. Not a menu of options — locked, production-tested config for TidyFactor documentation web portals.
+## `docs/index.html` Template
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title><PROJECT_NAME> Documentation</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Cairo:wght@400;600;700&family=Inter:wght@400;500;600;700;800&family=Fira+Code:wght@400;500&display=swap">
+  <style>
+    :root {
+      --theme-color: #0A2540;
+      --sidebar-width: 300px;
+    }
+    body {
+      font-family: 'Inter', 'Cairo', -apple-system, BlinkMacSystemFont, sans-serif;
+      color: #1e293b;
+      background-color: #ffffff;
+    }
+    /* Header & Brand styling */
+    .app-name-link {
+      font-weight: 800 !important;
+      font-size: 1.25rem !important;
+      color: #0A2540 !important;
+      letter-spacing: -0.02em;
+    }
+    /* Fixed Floating Sidebar Toggle Hamburger Button */
+    .sidebar-toggle {
+      position: fixed !important;
+      top: 14px !important;
+      left: 14px !important;
+      bottom: auto !important;
+      z-index: 1000 !important;
+      background: #0A2540 !important;
+      padding: 10px 12px !important;
+      border-radius: 8px !important;
+      box-shadow: 0 4px 12px rgba(10, 37, 64, 0.25) !important;
+      border: none !important;
+      cursor: pointer !important;
+      width: auto !important;
+      height: auto !important;
+      transition: transform 0.2s ease, background 0.2s ease !important;
+    }
+    .sidebar-toggle:hover {
+      background: #081C30 !important;
+      transform: scale(1.04);
+    }
+    .sidebar-toggle .sidebar-toggle-button {
+      display: flex !important;
+      flex-direction: column !important;
+      justify-content: center !important;
+      align-items: center !important;
+      gap: 4px !important;
+      background: transparent !important;
+      padding: 0 !important;
+      margin: 0 !important;
+      border: none !important;
+      width: auto !important;
+      height: auto !important;
+    }
+    .sidebar-toggle span {
+      display: block !important;
+      background-color: #ffffff !important;
+      height: 2px !important;
+      width: 20px !important;
+      margin: 0 !important;
+      border-radius: 2px !important;
+      float: none !important;
+      position: relative !important;
+    }
+    /* Sidebar Layout */
+    .sidebar {
+      padding-top: 60px !important;
+      padding-bottom: 40px !important;
+      background-color: #f8fafc !important;
+      border-right: 1px solid #e2e8f0 !important;
+    }
+    .sidebar ul li a {
+      font-weight: 500;
+      color: #475569;
+      transition: all 0.15s ease;
+      border-radius: 4px;
+    }
+    .sidebar ul li a:hover {
+      color: #0A2540;
+      background-color: #e2e8f0/50;
+    }
+    .sidebar ul li.active > a {
+      color: #0A2540 !important;
+      font-weight: 700 !important;
+      border-left: 3px solid #0A2540;
+      padding-left: 8px;
+    }
+    /* Content Styling & Typography */
+    .markdown-section {
+      max-width: 900px !important;
+      padding: 40px 45px !important;
+    }
+    .markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4 {
+      font-family: 'Inter', 'Cairo', sans-serif;
+      color: #0F172A;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+    }
+    .markdown-section h1 {
+      border-bottom: 1px solid #e2e8f0;
+      padding-bottom: 12px;
+      font-size: 2.1rem;
+    }
+    .markdown-section h2 {
+      font-size: 1.5rem;
+      margin-top: 2rem;
+    }
+    /* Code Blocks */
+    .markdown-section pre {
+      border-radius: 8px !important;
+      background-color: #0f172a !important;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    }
+    .markdown-section code {
+      font-family: 'Fira Code', monospace !important;
+      font-size: 0.9em;
+    }
+    .markdown-section p code {
+      background-color: #f1f5f9 !important;
+      color: #0f172a !important;
+      padding: 3px 6px !important;
+      border-radius: 4px !important;
+      border: 1px solid #cbd5e1 !important;
+    }
+    /* Table Styling */
+    .markdown-section table {
+      display: table !important;
+      width: 100% !important;
+      border-collapse: collapse !important;
+      border: 1px solid #e2e8f0 !important;
+      border-radius: 6px !important;
+      overflow: hidden !important;
+      margin: 20px 0 !important;
+    }
+    .markdown-section th {
+      background-color: #f8fafc !important;
+      color: #0f172a !important;
+      font-weight: 700 !important;
+      border-bottom: 2px solid #e2e8f0 !important;
+      padding: 10px 14px !important;
+    }
+    .markdown-section td {
+      border-bottom: 1px solid #e2e8f0 !important;
+      padding: 10px 14px !important;
+    }
+    /* Scrollbars */
+    ::-webkit-scrollbar {
+      width: 8px;
+      height: 8px;
+    }
+    ::-webkit-scrollbar-track {
+      background: #f1f5f9;
+    }
+    ::-webkit-scrollbar-thumb {
+      background: #cbd5e1;
+      border-radius: 4px;
+    }
+    ::-webkit-scrollbar-thumb:hover {
+      background: #94a3b8;
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: '<PROJECT_NAME>',
+      repo: '<REPO_URL>',
+      loadSidebar: true,
+      alias: {
+        '/.*/_sidebar.md': '/_sidebar.md'
+      },
+      subMaxLevel: 2,
+      auto2top: true,
+      search: {
+        placeholder: 'Search documentation...',
+        noData: 'No results found',
+        depth: 3
+      }
+    }
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+</body>
+</html>
+```
+Replace `<PROJECT_NAME>` from `docs/.doc-manifest.json`'s `project` field, and `<REPO_URL>` with project repository or developer link (`https://github.com/alwkala/TidyFactor-Go`).
+---
+## Critical Rules & Lessons Learned
+### 1. Subfolder Navigation Sidebar Alias
+- **CRITICAL**: Always configure `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` in `window.$docsify`. Without this alias, opening subfolder guides (e.g. `/#/guides/architecture-and-setup`) causes Docsify to look for `guides/_sidebar.md` and hide the sidebar menu!
+- **CRITICAL**: Use leading slashes `/` for all links in `_sidebar.md` (`/guides/admin-user-guide.md`, `/api/project.md`) so links resolve relative to the `/docs` root from any route depth.
+### 2. Localized Pages Inside Docs Root
+- **CRITICAL**: Docsify web root is `/docs`. Never link out of `/docs` using relative `../` paths (e.g. `../README.ar.md`), as Docsify SPA routing will throw `404 - Not Found`.
+- Always place localized landing pages inside `/docs` (e.g. `docs/README.ar.md`), rendering smoothly at `/#/README.ar.md`.
+### 3. Hamburger Toggle Button (`.sidebar-toggle`) Styling
+- Always style `.sidebar-toggle` and `.sidebar-toggle-button` with fixed positioning (`top: 14px; left: 14px; z-index: 1000`) and explicit `<span>` lines (`width: 20px; height: 2px; display: block`) so the hamburger button remains accessible without collapsing or overlapping sidebar text items.
+### 4. Cross-Platform Emojis & Typography
+- Country flag emojis (`🇸🇦`, `🇺🇸`) render as 2-letter codes (`SA`, `US`) on Windows Chrome/Edge. Use clean text badges (`[عربي]`, `[EN]`) in `_sidebar.md`.
+- Always load Google Fonts (`Cairo` for Arabic RTL, `Inter` for English LTR, `Fira Code` for code blocks) in `docs/index.html`.
+---
+## `_sidebar.md` Generation Rule
+Group by audience/purpose, root docs first, using leading slashes `/`:
+```markdown
+- 🌐 [Overview / النظرة العامة](/README.md)
+- 📖 [المقدمة بالعربية](/README.ar.md)
+- 💡 [رؤية المنظومة والشركة](/guides/vision-and-ecosystem.md)
+- [عربي] أدلة المستخدم (User Guides - AR)
+  - [دليل مالك الموقع (Admin User Guide)](/guides/admin-user-guide.md)
+  - [دليل تحرير المحتوى (Editing Pages Content)](/guides/pages-editing-guide.md)
+- [EN] Developer & Technical Guides
+  - [Quick Start Guide](/guides/quick-start.md)
+  - [Platform & System Specifications](/guides/system-specifications.md)
+  - [AI Coding & Agent Workflows](/guides/ai-agent-workflows.md)
+  - [Content Engine Architecture & API](/guides/content-engine.md)
+  - [Architecture & Setup Guide](/guides/architecture-and-setup.md)
+  - [Database & Storage Architecture](/guides/database-and-storage.md)
+  - [Security & System Hardening](/guides/security-and-hardening.md)
+  - [Production Deployment & Hosting](/guides/deployment-and-hosting.md)
+  - [CMS Content Engine & Backups](/guides/cms-content-engine-and-backups.md)
+- 📚 REST API Reference
+  - [API Endpoints Specifications](/api/project.md)
+---
+- 👨‍💻 Developed by [Alwkala](https://github.com/alwkala)
+```
+Regenerate the whole file each run so it never drifts from what's actually in `/docs`.
+---
+## Preview
+Local static server: `php -S localhost:3001 -t docs` or `npx docsify-cli serve docs`.

package/references/memory/mkdocs-config.md ADDED Viewed

@@ -0,0 +1,170 @@
+# 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/site-engines.md ADDED Viewed

@@ -0,0 +1,54 @@
+# Memory: Site Engines (Docsify vs. MkDocs Material)
+Technical evaluation matrix for documentation publishing engines supported by `tidyfactor-doc`.
+## Engine Comparison Matrix
+| Capability / Factor | ⚡ MkDocs Material (Static Compiler) | 📄 Docsify (Client-Side SPA) |
+|---|---|---|
+| **Architecture** | Static Site Generator (Python Markdown) | Client-Side SPA (`marked.js` in browser) |
+| **Output Type** | Pre-rendered static HTML (`site/`) | Single `index.html` fetching `.md` via AJAX |
+| **Build Dependency** | Python 3.10+, `pip install mkdocs-material` | Zero build step, zero compiler required |
+| **SEO & Crawlers** | 100/100 Perfect static HTML indexing | Limited (requires JS execution by bots) |
+| **Performance & CWV** | Instant initial paint, pre-cached assets | Client-side fetch delay on slow mobile networks |
+| **i18n & Localization** | Native parallel builds (`/` and `/ar/`) via `mkdocs-static-i18n` | Single page language or manual separate SPAs |
+| **Search Engine** | Lunr.js pre-indexed offline search (bilingual) | In-browser client-side fuzzy search |
+| **Styling & Theming** | Material for MkDocs + Neo-Brutalist CSS tokens | Custom CSS over Docsify default theme |
+| **Code Highlighting** | Pygments build-time syntax highlighting + line spans | Prism.js client-side syntax highlighting |
+| **Target Deployment** | Production doc portals, public SaaS products, multi-language sites | Rapid internal repo docs, single-file lightweight guides |
+---
+## Decision Logic & Recommendation Rules
+1. **Choose MkDocs Material if:**
+   - The documentation has more than 10 pages or complex multi-level hierarchy.
+   - Public SEO visibility and search engine discoverability are critical.
+   - The project is bilingual (Arabic RTL + English LTR) requiring dedicated language switches.
+   - The local environment has Python installed (`python --version` returns 3.10+).
+   - Production hosting supports static directory routing (`public_html/documentation/`).
+2. **Choose Docsify if:**
+   - The developer or server environment has **no Python runtime** and requires zero installation.
+   - The project needs an instant browsable site by dropping a single `index.html` into `/docs`.
+   - The documentation is primarily for internal developers within a repository.
+   - The site is hosted on GitHub Pages with zero CI build workflows.
+---
+## Two-Tier Multi-Language Documentation Pattern
+Both engines adhere to the TidyFactor Two-Tier Documentation standard:
+- **Canonical Technical SSOT**: Full API specifications, architecture, and code deep-dives maintained in Canonical English (`/docs/en/` or root) with First-Class Arabic (`/docs/ar/`).
+- **Localized Adoption Guides**: Quickstarts, tutorials, concepts, and command matrices for Tier 1/2 growth languages (`es`, `pt`, `fa`, `zh`, `de`, `fr`) providing high-conversion onboarding.
+---
+## Toolchain Verification Command
+```bash
+# Check if Python is available for MkDocs
+python --version 2>&1 || python3 --version 2>&1
+```
+- If Python is available: recommend **MkDocs Material** as primary production track.
+- If Python is not available: recommend **Docsify** as zero-dependency fallback.

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

@@ -0,0 +1,45 @@
+# 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.

package/references/memory/stacks/php.md ADDED Viewed

@@ -0,0 +1,33 @@
+# 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.