Deploy Documentation

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:

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)

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": "admin@admin.com",
        "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": "admin@demo.com",
        "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

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

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)