deploy-documentation

name	deploy-documentation
description	Tự động hoá quy trình chụp screenshot và cập nhật documentation sau mỗi lần build & deploy — discover routes, generate manifest, capture screenshots, update HTML. Hoạt động với mọi loại web application.
projectType	all

Deploy Documentation — Auto Screenshot & Docs Generator

Purpose

Skill này tự động hoá quy trình chụp ảnh màn hình và cập nhật documentation sau mỗi lần build & deploy sản phẩm. Thay vì developer phải truy cập thủ công từng trang, chụp ảnh, rồi cập nhật landing page — skill này thực hiện toàn bộ quy trình một cách tự động và nhất quán.

Vấn đề giải quyết:

• Sau khi build xong plugin/module/software, developer phải truy cập từng trang tính năng trên site
• Chụp ảnh thủ công, dễ sai sót (quên cập nhật mô tả)
• Tốn thời gian khi có nhiều route, lặp lại mỗi version

When to Use

• Sau mỗi lần release / deploy phiên bản mới
• Khi cần sync documentation screenshots với UI thực tế
• Khi thêm tính năng mới chưa có trong manifest
• Khi cần chụp ảnh từ nhiều site khác nhau (local, demo, client)

---

Architecture: 2 Phases

Phase 1: DISCOVER — Quét codebase → Suggest manifest entries
Phase 2: CAPTURE  — Đọc manifest → Login → Navigate → Screenshot → Update HTML

---

Phase 1: Route Discovery & Manifest Generation

Mục đích

Tự động quét codebase để phát hiện routes/pages, sau đó suggest thêm entries vào deploy_manifest.json.

Cách hoạt động

1. Quét routes — tìm tất cả route definitions trong codebase:

Project Type	Source files
Perfex CRM Module	config/my_routes.php + controller method names
Laravel App	routes/web.php, routes/api.php
WordPress Plugin	add_menu_page(), add_submenu_page() hooks
Next.js / Vite SPA	pages/ directory, router config files
Electron App	Window/view registrations
Generic	Navigation config files, sitemap

2. Quét menu registrations — tìm sidebar/nav menu items:

• Perfex CRM: $this->app_menu->add_sidebar_menu_item() calls
• WordPress: add_menu_page(), add_submenu_page()
• Generic: tìm navigation config files

3. Quét migration changelog:

• Parse logChanged() hoặc CHANGELOG.md để detect features mới chưa có trong manifest

4. Cross-reference với manifest:

• So sánh routes discovered vs entries đã khai báo → suggest entries còn thiếu

Discovery Scan Targets (Perfex CRM modules — example)

modules/{module}/config/my_routes.php       → Route definitions
modules/{module}/data_builder.php           → Menu items (add_sidebar_menu_item)
modules/{module}/controllers/*.php          → Controller methods = pages
modules/{module}/views/admin/**/*.php       → View templates
modules/{module}/migrations/*_version_*.php → Changelog (logChanged)

Output Format — Suggested Entry

{
  "id": "auto-discovered-{route}",
  "filename": "{Feature-Name}-{Product}.png",
  "title": "{Feature Name}",
  "route": "/admin/{module}/{controller}/{method}",
  "wait_for": "#app, .panel, .table-responsive",
  "section": "core-features",
  "actions_before": [
    { "action": "wait", "ms": 2000 }
  ],
  "_discovered_from": "controller: Builder.php → method: index()",
  "_status": "suggested"
}

IMPORTANT: Entries có _status: "suggested" cần user review và confirm trước khi chạy Phase 2. Agent MUST NOT auto-proceed.

Site Suggestion Logic (khi discover)

Loại page	Site đề xuất	Lý do
Admin management pages	local	Không cần real data
Charts, runtime reports	demo	Cần data đẹp, trực quan
Public embed / iframe	demo	Cần public view đã setup
Client-specific feature	client_x	Cần data thực tế của client

---

Phase 2: Screenshot Capture & Documentation Update

Prerequisites

• File deploy_manifest.json đã được review và xác nhận
• Site đang chạy và accessible tại base_url
• Credentials hợp lệ

Step 1: Build Site Groups

1. Đọc manifest.sites{} và manifest.default_site
2. Với mỗi entry trong screenshots[]:
   - Nếu entry có "site" key → site = sites[entry.site]
   - Nếu không → site = sites[default_site]
3. Group entries by site key → { local: [...], demo: [...], client_x: [...] }

Step 2: Login (một lần mỗi site)

Foreach unique_site in groups:
  site_config = sites[unique_site]
  1. Mở browser tab mới tại: {site_config.base_url}{site_config.login_url}
  2. Điền credentials:
       - email_selector ← site_config.login_form.email_selector
       - password_selector ← site_config.login_form.password_selector
  3. Click submit: site_config.login_form.submit_selector
  4. Chờ redirect hoặc dashboard element xuất hiện
  5. Lưu session/cookies cho site này
  Log: ✅ Logged in to {site_config.base_url} / ❌ Login failed

login_form supports:

• Perfex CRM: input[name='email'] + input[name='password']
• WordPress: input#user_login + input#user_pass
• Laravel / generic: any valid CSS selector

Step 3: Screenshot Loop

Foreach entry in manifest.screenshots[]:
  site_config = sites[entry.site || default_site]
  base_url    = site_config.base_url

  1. Navigate tới {base_url}{entry.route}
     Resolve dynamic tokens nếu có:
       {first_view_id}      → Scrape view list page → first row ID
       {first_view_route}   → Scrape view list page → first row route slug
       {first_public_route} → Scrape views → first with public_access indicator
       {latest_record_id}   → Scrape or sort by date → most recent ID

  2. Set viewport: entry.viewport || manifest.defaults.viewport

  3. Execute actions_before[] theo thứ tự:
       wait                → sleep(ms)
       click               → click(selector)
       click_first_visible → find first visible element → click
       scroll_down         → window.scrollBy(0, px)
       scroll_to           → element.scrollIntoView()
       type                → type text into selector (for search/filter inputs)

  4. Wait for: entry.wait_for selector to appear in DOM

  5. Capture screenshot:
       format = entry.format || manifest.defaults.format
       Save → {output.images_dir}/{entry.filename}

  Log: ✅ {entry.id} → {entry.filename} / ❌ reason

Step 4: HTML Update (Optional)

1. Đọc index.html
2. Cập nhật version number từ source code
3. Cập nhật date (Updated: {current month year})
4. Parse changelog từ migration file → inject vào #changelog-content
5. Verify tất cả <img src="images/..."> đều có file tương ứng
6. Save index.html

---

Manifest Format Reference

Tạo file deploy_manifest.json cùng folder với AGENTS.heraspec.md và thư mục heraspec/ của project/module đó — không nhất thiết là root của toàn bộ monorepo:

{
  "product": {
    "name": "Product Name",
    "tagline": "Short description",
    "version_source": "path/to/version_file",
    "changelog_source": "path/to/migration_or_changelog"
  },

  "sites": {
    "local": {
      "base_url": "https://localhost:PORT",
      "login_url": "/admin/authentication",
      "login_form": {
        "email_selector": "input[name='email']",
        "password_selector": "input[name='password']",
        "submit_selector": "button[type='submit']"
      },
      "credentials": {
        "email": "[e-mail]",
        "password": "password"
      },
      "description": "Local dev"
    },
    "demo": {
      "base_url": "https://demo.example.com",
      "login_url": "/admin/authentication",
      "login_form": {
        "email_selector": "input[name='email']",
        "password_selector": "input[name='password']",
        "submit_selector": "button[type='submit']"
      },
      "credentials": {
        "email": "[e-mail]",
        "password": "password"
      },
      "description": "Live demo site for marketing screenshots"
    }
  },

  "default_site": "local",

  "output": {
    "images_dir": "path/to/documentation/images",
    "html_file": "path/to/documentation/index.html"
  },

  "defaults": {
    "viewport": { "width": 1440, "height": 900 },
    "format": "png",
    "wait_ms": 2000
  },

  "screenshots": [
    {
      "id": "feature-overview",
      "filename": "Feature-Overview-ProductName.png",
      "title": "Feature Overview",
      "route": "/admin/module/page",
      "wait_for": "#app, .panel, .table-responsive",
      "section": "core-features",
      "actions_before": [
        { "action": "wait", "ms": 2000 }
      ]
    },
    {
      "id": "feature-on-demo",
      "site": "demo",
      "filename": "Feature-Demo-ProductName.png",
      "title": "Feature (Demo Data)",
      "route": "/admin/module/page",
      "wait_for": ".chart-container",
      "section": "core-features",
      "actions_before": [
        { "action": "wait", "ms": 3000 }
      ]
    }
  ]
}

Dynamic Route Tokens

Token	Resolution
{first_view_id}	ID của record đầu tiên trong view list
{first_view_route}	Route slug của view đầu tiên
{first_public_route}	Route của view public đầu tiên
{latest_record_id}	ID của record mới nhất

Agent resolves các token này bằng cách scrape trang list hoặc query database.

---

Prompt Templates

Full workflow (Discover + Capture):

Sử dụng skill deploy-documentation.
Project: {module_path}
Manifest: {manifest_path}

1. Phase 1: Quét codebase tại {module_path}, phát hiện routes/features chưa có trong manifest, suggest entries mới (đề xuất site phù hợp cho từng entry)
2. Tôi sẽ review và confirm manifest
3. Phase 2: Login vào từng site trong manifest, chụp tất cả screenshots, lưu vào images_dir
4. Cập nhật index.html với ảnh mới và changelog

Chỉ chụp ảnh — tất cả sites (manifest đã sẵn):

Sử dụng skill deploy-documentation.
Đọc manifest tại {manifest_path}.
Login vào từng site được khai báo, chụp tất cả screenshots theo manifest, lưu vào output.images_dir.

Chỉ chụp ảnh — 1 site cụ thể:

Sử dụng skill deploy-documentation.
Đọc manifest tại {manifest_path}.
Chỉ chụp các screenshots thuộc site "demo".
Login vào demo site, navigate và capture, lưu vào images_dir.

Chỉ chụp lại 1 số ảnh cụ thể:

Sử dụng skill deploy-documentation.
Đọc manifest tại {manifest_path}.
Chỉ chụp lại các entries: {id1}, {id2}, {id3}.
Sử dụng site mặc định (default_site) trừ khi entry có khai báo site riêng.

Chỉ discover — suggest entries mới:

Sử dụng skill deploy-documentation.
Quét codebase tại {module_path}, so sánh với manifest tại {manifest_path}.
Suggest entries mới cho features/routes chưa được khai báo.
Với mỗi entry mới: đề xuất site phù hợp (local nếu là admin page, demo nếu cần real-data screenshot).
Không tự thêm vào manifest — liệt kê để tôi review trước.

---

Compatibility — Supported Project Types

Project Type	Route Discovery Source
Perfex CRM Module	my_routes.php + controller methods
Laravel App	routes/web.php + routes/api.php
WordPress Plugin	add_menu_page() + add_submenu_page()
Next.js / Vite SPA	pages/ directory + router config
Electron App	Window/view registrations
Generic Web App	Navigation config files, sitemap

Mỗi project chỉ cần 1 file deploy_manifest.json riêng. Cùng skill, cùng workflow.

---

File Structure (per project/module)

deploy_manifest.json nằm cùng folder với AGENTS.heraspec.md và heraspec/ của module/project đó:

{heraspec_workspace_dir}/        ← Thư mục chứa AGENTS.heraspec.md
├── AGENTS.heraspec.md
├── heraspec/
├── deploy_manifest.json         ← Đặt tại đây
└── documentation/
    ├── index.html
    └── images/

Ví dụ với Perfex CRM (mỗi module là một workspace HeraSpec riêng):

perfex_crm/
└── modules/
    ├── data_builder/
    │   ├── AGENTS.heraspec.md
    │   ├── heraspec/
    │   ├── deploy_manifest.json    ← manifest của data_builder
    │   └── documentation/
    └── another_module/
        ├── AGENTS.heraspec.md
        ├── heraspec/
        ├── deploy_manifest.json    ← manifest riêng của another_module
        └── documentation/

Rule: deploy_manifest.json luôn nằm cùng cấp với AGENTS.heraspec.md và heraspec/ — dù workspace đó là module con hay project độc lập.

---

Inputs

• deploy_manifest.json — manifest file của project (xem templates/deploy_manifest.template.json)
• Codebase path — để Phase 1 discover routes
• Running site — để Phase 2 capture screenshots

Outputs

• Screenshot PNG/WebP files tại output.images_dir
• Updated index.html tại output.html_file
• Suggested entries (Phase 1 only) — danh sách để user review

Limitations

• Yêu cầu browser agent có khả năng điều khiển browser (navigate, click, screenshot)
• Login session không persistent giữa các lần chạy — phải login lại mỗi session
• Dynamic tokens ({first_view_id}, v.v.) cần site đang có dữ liệu thực
• HTML auto-update chỉ hoạt động nếu index.html có structure đúng format (có #changelog-content, <img> tags với đúng src pattern)