apt-mcp-agent-setup 3.5.36 → 3.5.61

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 (183) hide show
  1. package/README.md +123 -123
  2. package/bin/cli.js +1 -1
  3. package/build-input.json +302 -241
  4. package/bundle/NOTICES.md +0 -0
  5. package/bundle/core.enc +0 -0
  6. package/bundle/mcp-rules.enc +0 -0
  7. package/bundle/skills-aso.enc +0 -0
  8. package/bundle/skills-ba.enc +0 -0
  9. package/bundle/skills-base.enc +0 -0
  10. package/bundle/skills-be.enc +0 -0
  11. package/bundle/skills-design.enc +0 -0
  12. package/bundle/skills-fe.enc +0 -0
  13. package/bundle/skills-marketing.enc +0 -0
  14. package/bundle/skills-mobile.enc +0 -0
  15. package/bundle/skills-pm.enc +0 -0
  16. package/docs/technical-sources.md +7 -7
  17. package/integrity-manifest.json +183 -178
  18. package/package.json +1 -1
  19. package/release-check.js +30 -30
  20. package/src/backends/browser-tools.js +1 -1
  21. package/src/backends/index-cache-authority.js +1 -1
  22. package/src/backends/index-command.js +1 -1
  23. package/src/backends/index-contract.json +11 -11
  24. package/src/backends/index-maintenance.js +1 -1
  25. package/src/backends/index-store.js +1 -1
  26. package/src/backends/linked-worktrees.js +1 -0
  27. package/src/backends/profiles.js +1 -1
  28. package/src/backends/review_graph.py +125 -103
  29. package/src/backends/source-discovery.js +1 -1
  30. package/src/core/admission-fence.js +1 -1
  31. package/src/core/aso-import.js +1 -1
  32. package/src/core/backend-lease-recovery.js +1 -1
  33. package/src/core/boot-evidence.js +1 -1
  34. package/src/core/caller-context.js +1 -1
  35. package/src/core/catalog.js +1 -1
  36. package/src/core/claude-caller-authority.js +1 -1
  37. package/src/core/claude-invocation.js +1 -1
  38. package/src/core/claude-launch-recovery.js +1 -1
  39. package/src/core/claude-native.js +1 -1
  40. package/src/core/claude-plan.js +1 -1
  41. package/src/core/claude-transcript-scan.js +1 -1
  42. package/src/core/claude-worker-transcript.js +1 -1
  43. package/src/core/codex-host-metadata.js +1 -1
  44. package/src/core/codex-transcript-receipt.js +1 -1
  45. package/src/core/connection-inspector.js +1 -1
  46. package/src/core/content-hash-cache.js +1 -1
  47. package/src/core/context-metrics.js +1 -1
  48. package/src/core/doctor.js +1 -1
  49. package/src/core/draining-completion.js +1 -1
  50. package/src/core/execution.js +1 -1
  51. package/src/core/git-context.js +1 -1
  52. package/src/core/hook-bridge.js +1 -1
  53. package/src/core/hook-diagnostics.js +1 -1
  54. package/src/core/hook-lease.js +1 -1
  55. package/src/core/host-adapters.js +1 -1
  56. package/src/core/interrupted-boot-transport-proof.js +1 -1
  57. package/src/core/interrupted-natural-closure-proof.js +1 -1
  58. package/src/core/interrupted-operation-audit.js +1 -1
  59. package/src/core/interrupted-transport-proof.js +1 -1
  60. package/src/core/ipc-envelope.js +1 -1
  61. package/src/core/legacy-retirement-proof.js +1 -1
  62. package/src/core/memory-scope.js +1 -1
  63. package/src/core/memory-store.js +1 -1
  64. package/src/core/model-inventory.js +1 -1
  65. package/src/core/model-routing.js +1 -1
  66. package/src/core/native-dispatch.js +1 -1
  67. package/src/core/native-receipt.js +1 -1
  68. package/src/core/native-retirement.js +1 -1
  69. package/src/core/node-version.js +1 -1
  70. package/src/core/npm-cli.js +1 -1
  71. package/src/core/owned-command-child.js +1 -1
  72. package/src/core/owned-command.js +1 -1
  73. package/src/core/owned-lock.js +1 -1
  74. package/src/core/owned-process.js +1 -1
  75. package/src/core/pipeline-journal.js +1 -1
  76. package/src/core/presentations.js +1 -1
  77. package/src/core/quality-artifacts.js +1 -1
  78. package/src/core/quality.js +1 -1
  79. package/src/core/read-command.js +1 -1
  80. package/src/core/readonly-skill.js +1 -1
  81. package/src/core/recovery-archive.js +1 -1
  82. package/src/core/recovery-proof.js +1 -1
  83. package/src/core/resource-transaction.js +1 -1
  84. package/src/core/run-checkpoint.js +1 -1
  85. package/src/core/run-compatibility.js +1 -1
  86. package/src/core/run-owner.js +1 -0
  87. package/src/core/run-state-codec.js +1 -1
  88. package/src/core/runtime-authority.js +1 -1
  89. package/src/core/runtime-info.js +1 -1
  90. package/src/core/runtime-ownership.js +1 -1
  91. package/src/core/session.js +1 -1
  92. package/src/core/shared-checkout.js +1 -1
  93. package/src/core/skill-companions.js +1 -1
  94. package/src/core/skill-names.js +1 -1
  95. package/src/core/storage-retry.js +1 -1
  96. package/src/core/tool-contracts.js +1 -1
  97. package/src/core/transport-boot-contract.json +12 -12
  98. package/src/core/transport-close-contract.json +10 -10
  99. package/src/core/transport-contract.json +10 -10
  100. package/src/core/transport-pending-boot-contract.json +12 -12
  101. package/src/core/update-control.js +1 -1
  102. package/src/core/upgrade-runs.js +1 -1
  103. package/src/core/upgrade-stop.js +1 -1
  104. package/src/core/windows-job.js +1 -1
  105. package/src/core/workflow-policy.js +1 -1
  106. package/src/core/workspace-generation.js +1 -1
  107. package/src/core/workspace-path.js +1 -1
  108. package/src/installer/bounded-command.js +1 -1
  109. package/src/installer/candidate-preflight.js +1 -1
  110. package/src/installer/claude-commands.js +1 -1
  111. package/src/installer/codex-hook-trust.js +1 -0
  112. package/src/installer/connection-activation.js +1 -1
  113. package/src/installer/connection-supervisor.js +1 -1
  114. package/src/installer/deployment-draft.js +1 -1
  115. package/src/installer/gateway-context.js +1 -1
  116. package/src/installer/gateway-migration.js +1 -1
  117. package/src/installer/gateway-runtime.js +1 -1
  118. package/src/installer/global-setup.js +1 -1
  119. package/src/installer/hook-context-client.js +1 -1
  120. package/src/installer/hook-dispatcher.js +179 -179
  121. package/src/installer/host-hooks.js +1 -1
  122. package/src/installer/index-interruption-recovery.js +1 -1
  123. package/src/installer/index-recovery.js +1 -1
  124. package/src/installer/install-intent.js +1 -1
  125. package/src/installer/interrupted-operation-recovery.js +1 -1
  126. package/src/installer/legacy-prepared-plan.js +1 -1
  127. package/src/installer/legacy-registration.js +1 -1
  128. package/src/installer/managed-config.js +1 -1
  129. package/src/installer/migration-scope.js +1 -1
  130. package/src/installer/platform-config.js +1 -1
  131. package/src/installer/prerequisites.js +1 -1
  132. package/src/installer/presentations.js +1 -1
  133. package/src/installer/project-outcome.js +1 -1
  134. package/src/installer/project-setup.js +1 -1
  135. package/src/installer/recovery-backup-retention.js +1 -1
  136. package/src/installer/registration-closure.js +1 -1
  137. package/src/installer/registration-plan.js +1 -1
  138. package/src/installer/registration-receipt.js +1 -1
  139. package/src/installer/registrations.js +1 -1
  140. package/src/installer/runtime-activation.js +1 -1
  141. package/src/installer/runtime-child.js +1 -1
  142. package/src/installer/runtime-cleanup.js +1 -1
  143. package/src/installer/runtime-lock.js +1 -1
  144. package/src/installer/runtime-store.js +1 -1
  145. package/src/installer/runtime-supervisor.js +1 -1
  146. package/src/installer/setup-wizard.js +1 -1
  147. package/src/installer/stale-run-release.js +1 -1
  148. package/src/installer/uninstall.js +1 -0
  149. package/src/installer/update-addons.js +1 -1
  150. package/src/installer/update-cleanup.js +1 -1
  151. package/src/installer/update-executor.js +1 -1
  152. package/src/installer/update-history.js +1 -1
  153. package/src/installer/update-registration.js +1 -1
  154. package/src/installer/update-report.js +1 -1
  155. package/src/installer/update-request.js +1 -1
  156. package/src/installer/update-scope.js +1 -1
  157. package/src/installer/workspace-registry.js +1 -1
  158. package/src/installer/workspace-transaction.js +1 -1
  159. package/src/installer/workspace-update.js +1 -1
  160. package/src/license/crypto.js +1 -1
  161. package/src/license/fingerprint.js +1 -1
  162. package/src/license/terms.js +1 -1
  163. package/src/license/verify.js +1 -1
  164. package/src/presets/index.js +1 -1
  165. package/src/proxy/backends.js +1 -1
  166. package/src/proxy/browser-sessions.js +1 -1
  167. package/src/proxy/core-tools.js +1 -1
  168. package/src/proxy/pipeline.js +1 -1
  169. package/src/proxy/public-catalog.js +1 -1
  170. package/src/proxy/router.config.js +1 -1
  171. package/src/proxy/router.js +1 -1
  172. package/src/proxy/run-summary.js +1 -1
  173. package/src/proxy/server-instructions.js +1 -0
  174. package/src/proxy/server.js +1 -1
  175. package/src/proxy/workspace-gateway.js +1 -1
  176. package/src/templates/AGENTS.md +1 -1
  177. package/src/templates/CLAUDE.md +1 -1
  178. package/src/templates/GEMINI.md +1 -1
  179. package/src/templates/apt-runtime.md +5 -4
  180. package/src/templates/copilot-instructions.md +1 -1
  181. package/src/templates/cursorrules.mdc +1 -1
  182. package/src/templates/mcp-tools.md +4 -4
  183. package/src/templates/windsurfrules.md +1 -1
package/README.md CHANGED
@@ -1,123 +1,123 @@
1
- # Core MCP AI Agent (`apt-mcp-agent-setup`)
2
-
3
- APT 3.5.36: [an update reads old runs to the end, a checkpoint reads the workspace once, and a Codex worker records its own verdict](docs/releases/3.5.36.md). APT 3.5.35: [a checkpoint answers with a summary of the run](docs/releases/3.5.35.md). APT 3.5.34: [an update waits for a requested cancel to finish](docs/releases/3.5.34.md). APT 3.5.33: [an update is not held by a run that has ended, and a review round that finds new defects is progress](docs/releases/3.5.33.md). APT 3.5.32: [a run verifies and waits next to the run of another host session](docs/releases/3.5.32.md). APT 3.5.31: [several host sessions work in one workspace at the same time](docs/releases/3.5.31.md). APT 3.5.30: [an update catches the review index up and keeps the resource copies of three updates](docs/releases/3.5.30.md). APT 3.5.29: [the review index no longer walks dependency folders and recovery backups](docs/releases/3.5.29.md). APT 3.5.28: [on Claude Code a worker gets a cheaper model than the coordinator when its task allows](docs/releases/3.5.28.md). APT 3.5.27: [an update closes the observation a run holds of a stopped worker](docs/releases/3.5.27.md). APT 3.5.26: [a session is no longer locked out by its directory, a finished worker or a slow hook](docs/releases/3.5.26.md). APT 3.5.25: [a rename that Windows refuses for a moment no longer fails an update](docs/releases/3.5.25.md). APT 3.5.24: [a request whose connection is gone is retired without a typed cancel line](docs/releases/3.5.24.md). APT 3.5.23: [a request of a closed connection no longer holds an update](docs/releases/3.5.23.md). APT 3.5.22: [an update is no longer held by state of an agent session that is gone](docs/releases/3.5.22.md). APT 3.5.21: [update scope, hook availability, runaway worker loops, Claude Code slash entries and parallel writers](docs/releases/3.5.21.md). Client updates still use `npx apt-mcp-agent-setup@latest update`, which now updates the project it runs in; add `--all-projects` for every registered project.
4
-
5
- APT 3.5.18: [verified index shutdown recovery](docs/releases/3.5.18.md).
6
-
7
- APT 3.5.0 candidate: [build and gate report](docs/apt-3.5.0-build-report.md), [runtime migration and recovery](docs/apt-3.5.0-migration.md). An explicit update cancels unfinished runs in its scope while preserving files and history. Serving activation still requires direct process evidence.
8
-
9
-
10
- Nguồn kỹ thuật và nhánh tham khảo được quản lý tại [Technical Sources Registry](docs/technical-sources.md). Khi thêm một repo, skill, backend hoặc kỹ thuật mới, hãy ghi nguồn và bằng chứng pin/license vào danh mục trước khi tích hợp. Mỗi đợt cập nhật source APT chạy `npm run sources:validate` offline; dùng `npm run sources:refresh -- --json` để kiểm tra upstream có chủ đích. Refresh chỉ xuất báo cáo đề xuất. Xem [checklist release](docs/technical-sources-release-checklist.md) trước khi nâng nguồn hoặc đóng gói.
11
-
12
- > Bộ cổng kết nối AI Agent bảo mật, tích hợp hệ thống quản lý License Key và Skill bundle mã hóa động dành cho doanh nghiệp.
13
-
14
- ---
15
-
16
- ## 📋 Tổng Quan Hệ Thống
17
-
18
- Core MCP AI Agent được phân phối dưới dạng một bộ cài đặt tự động (`npm package`). Hệ thống cho phép phân phối các kỹ năng (Skills) và tác nhân (Agents) độc quyền của công ty một cách bảo mật tới máy của lập trình viên (Client) mà không lo lộ mã nguồn hay bị sử dụng trái phép ngoài phạm vi thiết bị được cấp quyền.
19
-
20
- ```
21
- +-----------------------------------------------+
22
- | Admin (Offline Machine) |
23
- | - master.key (Signature) |
24
- | - bundle.key (AES-256 Encryption Key) |
25
- +----------------------+------------------------+
26
- |
27
- | 1. Build & Encrypt (.enc)
28
- | 2. Publish Package (GitLab Package Registry)
29
- v
30
- +----------------------+------------------------+
31
- | GitLab Private NPM Registry |
32
- | - Package: apt-mcp-agent-setup |
33
- | - Contains: Obfuscated installer & Encrypted |
34
- | skills (*.enc) |
35
- +----------------------+------------------------+
36
- |
37
- | 3. npx apt-mcp-agent-setup install
38
- | --key <LICENSE_KEY>
39
- v
40
- +----------------------+------------------------+
41
- | Developer's Local Machine |
42
- | - Verifies License with Hardware Device ID |
43
- | - Decrypts skills to local workspace |
44
- | - Registers MCP Server to IDE (Antigravity) |
45
- +-----------------------------------------------+
46
- ```
47
-
48
- ---
49
-
50
- ## 📚 Tài Liệu Hướng Dẫn Nhanh
51
-
52
- Hệ thống được chia làm hai vai trò vận hành chính. Vui lòng tham khảo tài liệu hướng dẫn chi tiết tương ứng:
53
-
54
- ### 1. Dành Cho Quản Trị Viên (Admin)
55
- 👉 Xem tại: **[Hướng Dẫn Triển Khai & Cấp Khóa (Admin)](file:///c:/Users/admin/Documents/Projects/MCP_AI_Agent/base_mcp_ai_agent/docs/admin-guideline.md)**
56
- * **Nội dung bao gồm**:
57
- * Các nguyên tắc bảo mật và lưu trữ khóa ngoại tuyến (`master.key`, `bundle.key`).
58
- * Quy trình build, đóng gói mã hóa AES-256 các Skill thành tệp `.enc` và xáo trộn mã JS bằng `javascript-obfuscator`.
59
- * Cách publish package lên GitLab Package Registry cá nhân/doanh nghiệp.
60
- * Hướng dẫn chạy CLI `gen-key.js` để cấp License Key giới hạn theo thời gian và Device ID cho lập trình viên.
61
-
62
- ### 2. Dành Cho Lập Trình Viên (Developer)
63
- 👉 Xem tại: **[Hướng Dẫn Cài Đặt & Sử Dụng (Developer)](file:///c:/Users/admin/Documents/Projects/MCP_AI_Agent/base_mcp_ai_agent/docs/developer-guideline.md)**
64
- * **Nội dung bao gồm**:
65
- * Cách thiết lập xác thực `.npmrc` để truy cập GitLab Package Registry riêng tư của công ty.
66
- * Cách lấy Device ID phần cứng thông qua lệnh `npx apt-mcp-agent-setup init`.
67
- * Lệnh cài đặt tự động AI Agent vào workspace dự án và đăng ký cổng kết nối vào IDE.
68
- * Kiểm tra trạng thái hoạt động và thời hạn License Key.
69
- * Cơ chế tự động dọn dẹp (xóa sạch tài nguyên độc quyền) khi License hết hạn.
70
- * Hướng dẫn sử dụng các Slash Commands nâng cao: `/plan`, `/tdd`, `/debug`, `/verify`, `/to-issues`.
71
-
72
- ---
73
-
74
- ## ⚡ Tóm Tắt Quy Trình Phân Phối Trọn Gói (Deploy/Publish)
75
-
76
- ### Bước 1: Build đóng gói mã hóa (Admin)
77
- Đảm bảo bạn đã có các file khóa bảo mật trong thư mục `admin/` và version trong `package.json`, `package-lock.json` đã đồng bộ. Phiên bản source chuẩn bị phát hành là `3.5.18`. Chạy:
78
- ```bash
79
- npm run deploy
80
- ```
81
-
82
- Chọn **3** để build source hiện tại, ký runtime, đóng gói tarball, kiểm tra gói và publish lên npm. Luồng mặc định không yêu cầu đường dẫn JSON nghiệm thu và không tự tăng version. npm có thể yêu cầu đăng nhập hoặc xác thực khi publish.
83
-
84
- Nếu chỉ build local sau khi đã chọn version, chạy:
85
- ```bash
86
- npm run build
87
- ```
88
- Lệnh build mã hóa thư mục `.agents/` và `src/templates` thành các file `.enc` trong thư mục `bundle/`, sau đó build mã nguồn JS đã được xáo trộn ra thư mục `dist/`. Nếu `npm run deploy` đã mở từ trước rồi source thay đổi, hãy thoát menu cũ và chạy lại để nạp script mới. Menu cũ tự dừng trước khi build hoặc publish, tránh phát hành với logic version cũ.
89
-
90
- ### Bước 2: Kiểm tra bản phát hành (Admin)
91
-
92
- Menu deploy thực hiện publish sau khi package gate pass. Không cần chạy thêm lệnh publish trong `dist/`. Nếu đã đặt biến `APT_RELEASE_ACCEPTANCE`, deploy dùng luồng artifact đã nghiệm thu thay cho build source; bỏ biến đó để dùng luồng mặc định.
93
-
94
- Quyết định phát hành `3.5.15` và những phần kiểm thử local chưa hoàn tất được ghi tại [ghi chú phát hành](docs/releases/3.5.15.md). Sau publish, người dùng tiếp tục cập nhật bằng một lệnh:
95
-
96
- ```bash
97
- npx apt-mcp-agent-setup@latest update
98
- ```
99
-
100
- ### Bước 3: Sinh License Key cho Dev/QC/BA/PM (Admin)
101
- Khi nhận được Device ID từ nhân viên, hãy chạy CLI sinh khóa. Bạn có thể chỉ định một hoặc nhiều Preset ghép nối (Stackable Presets) ngăn cách bằng dấu phẩy:
102
- ```bash
103
- # Cấp khóa cho Dev di động Flutter
104
- node admin/gen-key.js --device <DEVICE_ID> --user "nguyen-van-a" --expires 2026-12-31 --preset mobile-flutter
105
-
106
- # Cấp khóa tích hợp: Dev React + Quyền quản lý dự án (PM) + Tích hợp thiết kế Figma
107
- node admin/gen-key.js --device <DEVICE_ID> --user "tran-van-b" --expires 2026-12-31 --preset fe-react,pm,figma
108
- ```
109
- Copy chuỗi License Key xuất ra và gửi cho người dùng.
110
-
111
- ### Bước 4: Cài đặt & Sử dụng (Developer / QC / BA / PM)
112
- Người dùng không cần cấu hình bất kỳ tệp tin xác thực `.npmrc` nào. Hãy mở terminal tại thư mục gốc dự án và chạy trực tiếp lệnh cài đặt:
113
- ```bash
114
- npx apt-mcp-agent-setup@latest install --key <LICENSE_KEY_ĐÃ_NHẬN>
115
- ```
116
-
117
- > [!IMPORTANT]
118
- > **Lưu ý quan trọng**: Luôn mở terminal và chạy lệnh trên tại **thư mục gốc của dự án** bạn muốn cấu hình AI Agent. Không chạy ở thư mục người dùng chung (`~` hoặc `C:\Users\Username`). Mỗi dự án sẽ được cấp một vùng làm việc độc lập chứa các Skill (.agents/) và bộ nhớ (.memory/) riêng biệt để đảm bảo hiệu quả làm việc và bảo mật.
119
-
120
- Hệ thống sẽ tự động cấu hình môi trường, giải mã các Kỹ năng phù hợp với Preset được cấp trong License Key và tích hợp thẳng vào IDE (Antigravity IDE, Claude Code, Cursor, hoặc VS Code).
121
-
122
-
123
-
1
+ # Core MCP AI Agent (`apt-mcp-agent-setup`)
2
+
3
+ APT 3.5.61: [the code index leaves linked git worktrees out, an index that ran out of time can be built again, and a worker is never told to act as the coordinator](docs/releases/3.5.61.md). APT 3.5.60: [Claude Code reviews and writers are seen again, Codex hooks run in VS Code, and answers about a run are small](docs/releases/3.5.60.md). APT 3.5.59: [an update goes on past a connection its host closes, and a session handover names what holds it](docs/releases/3.5.59.md). APT 3.5.58: [an APT update no longer makes the reviews of open runs stale, and a session without a host link says which session its thread belongs to](docs/releases/3.5.58.md). APT 3.5.57: [a reviewer reserved at acceptance completes a high-risk run when the coordinator checkpoints it](docs/releases/3.5.57.md). APT 3.5.56: [a writer loads its quality skill before the first write, workers are told how to recover from a refusal, and an update names the connections that hold it](docs/releases/3.5.56.md). APT 3.5.55: [a change run writes with ponytail-lazy-dev and a document run with humanizer, whatever was routed before them](docs/releases/3.5.55.md). APT 3.5.54: [an update held by a running agent session names its application, its session, the state of the run and how to release it](docs/releases/3.5.54.md). APT 3.5.53: [workers read with the shell in more of the ways they do, and a finished verification keeps its result while the run is locked](docs/releases/3.5.53.md). APT 3.5.52: [a workspace with many runs no longer locks out pipeline_next or research agents, and reviewers read more without a writer](docs/releases/3.5.52.md). APT 3.5.51: [a connection whose runtime is slow to start retries instead of losing its tools, and never holds an update](docs/releases/3.5.51.md). APT 3.5.50: [Antigravity subagents, reviewers that chain reads, and fewer runs raised to high risk](docs/releases/3.5.50.md). APT 3.5.49: [a run uses the skills and the specialist its task was routed to, on every host](docs/releases/3.5.49.md). APT 3.5.48: [a Codex coordinator can spawn the worker APT reserved although Codex encrypts the spawn message](docs/releases/3.5.48.md). APT 3.5.47: [`uninstall` removes APT from a project, or from the machine, and keeps what is yours](docs/releases/3.5.47.md). APT 3.5.46: [a Codex coordinator can spawn the worker APT reserved, whatever name the Codex hook gives the spawn tool](docs/releases/3.5.46.md). APT 3.5.45: [APT's hooks run on Codex without a manual step, a worker gets its spawn arguments ready to pass, and a connection answers its host before its runtime boots](docs/releases/3.5.45.md). APT 3.5.44: [a Codex reviewer's verdict is found in code mode, a reviewer can be added at acceptance, and a Codex worker gets its APT tools on a busy machine](docs/releases/3.5.44.md). APT 3.5.43: [an update asks a busy Windows again before it gives up on an ended connection](docs/releases/3.5.43.md). APT 3.5.42: [an interrupted index build is recovered on your confirmation instead of a restart of Windows](docs/releases/3.5.42.md). APT 3.5.41: [an update goes on past a live connection that could not read its own start](docs/releases/3.5.41.md). APT 3.5.40: [a worker gets a model per task whatever words its coordinator used for the spawn tool](docs/releases/3.5.40.md). APT 3.5.39: [an index build accepts a file CodeGraph skips for its size, and a Claude Code session keeps the link that independent review needs](docs/releases/3.5.39.md). APT 3.5.38: [one reviewer per item, findings that stay closed, and a threshold for what blocks](docs/releases/3.5.38.md). APT 3.5.37: [hooks stay within their deadline, a checkpoint reads a quarter of the files, an item round needs fewer calls, and a document task gets a document pipeline](docs/releases/3.5.37.md). APT 3.5.36: [an update reads old runs to the end, a checkpoint reads the workspace once, and a Codex worker records its own verdict](docs/releases/3.5.36.md). APT 3.5.35: [a checkpoint answers with a summary of the run](docs/releases/3.5.35.md). APT 3.5.34: [an update waits for a requested cancel to finish](docs/releases/3.5.34.md). APT 3.5.33: [an update is not held by a run that has ended, and a review round that finds new defects is progress](docs/releases/3.5.33.md). APT 3.5.32: [a run verifies and waits next to the run of another host session](docs/releases/3.5.32.md). APT 3.5.31: [several host sessions work in one workspace at the same time](docs/releases/3.5.31.md). APT 3.5.30: [an update catches the review index up and keeps the resource copies of three updates](docs/releases/3.5.30.md). APT 3.5.29: [the review index no longer walks dependency folders and recovery backups](docs/releases/3.5.29.md). APT 3.5.28: [on Claude Code a worker gets a cheaper model than the coordinator when its task allows](docs/releases/3.5.28.md). APT 3.5.27: [an update closes the observation a run holds of a stopped worker](docs/releases/3.5.27.md). APT 3.5.26: [a session is no longer locked out by its directory, a finished worker or a slow hook](docs/releases/3.5.26.md). APT 3.5.25: [a rename that Windows refuses for a moment no longer fails an update](docs/releases/3.5.25.md). APT 3.5.24: [a request whose connection is gone is retired without a typed cancel line](docs/releases/3.5.24.md). APT 3.5.23: [a request of a closed connection no longer holds an update](docs/releases/3.5.23.md). APT 3.5.22: [an update is no longer held by state of an agent session that is gone](docs/releases/3.5.22.md). APT 3.5.21: [update scope, hook availability, runaway worker loops, Claude Code slash entries and parallel writers](docs/releases/3.5.21.md). Client updates still use `npx apt-mcp-agent-setup@latest update`, which now updates the project it runs in; add `--all-projects` for every registered project.
4
+
5
+ APT 3.5.18: [verified index shutdown recovery](docs/releases/3.5.18.md).
6
+
7
+ APT 3.5.0 candidate: [build and gate report](docs/apt-3.5.0-build-report.md), [runtime migration and recovery](docs/apt-3.5.0-migration.md). An explicit update cancels unfinished runs in its scope while preserving files and history. Serving activation still requires direct process evidence.
8
+
9
+
10
+ Nguồn kỹ thuật và nhánh tham khảo được quản lý tại [Technical Sources Registry](docs/technical-sources.md). Khi thêm một repo, skill, backend hoặc kỹ thuật mới, hãy ghi nguồn và bằng chứng pin/license vào danh mục trước khi tích hợp. Mỗi đợt cập nhật source APT chạy `npm run sources:validate` offline; dùng `npm run sources:refresh -- --json` để kiểm tra upstream có chủ đích. Refresh chỉ xuất báo cáo đề xuất. Xem [checklist release](docs/technical-sources-release-checklist.md) trước khi nâng nguồn hoặc đóng gói.
11
+
12
+ > Bộ cổng kết nối AI Agent bảo mật, tích hợp hệ thống quản lý License Key và Skill bundle mã hóa động dành cho doanh nghiệp.
13
+
14
+ ---
15
+
16
+ ## 📋 Tổng Quan Hệ Thống
17
+
18
+ Core MCP AI Agent được phân phối dưới dạng một bộ cài đặt tự động (`npm package`). Hệ thống cho phép phân phối các kỹ năng (Skills) và tác nhân (Agents) độc quyền của công ty một cách bảo mật tới máy của lập trình viên (Client) mà không lo lộ mã nguồn hay bị sử dụng trái phép ngoài phạm vi thiết bị được cấp quyền.
19
+
20
+ ```
21
+ +-----------------------------------------------+
22
+ | Admin (Offline Machine) |
23
+ | - master.key (Signature) |
24
+ | - bundle.key (AES-256 Encryption Key) |
25
+ +----------------------+------------------------+
26
+ |
27
+ | 1. Build & Encrypt (.enc)
28
+ | 2. Publish Package (GitLab Package Registry)
29
+ v
30
+ +----------------------+------------------------+
31
+ | GitLab Private NPM Registry |
32
+ | - Package: apt-mcp-agent-setup |
33
+ | - Contains: Obfuscated installer & Encrypted |
34
+ | skills (*.enc) |
35
+ +----------------------+------------------------+
36
+ |
37
+ | 3. npx apt-mcp-agent-setup install
38
+ | --key <LICENSE_KEY>
39
+ v
40
+ +----------------------+------------------------+
41
+ | Developer's Local Machine |
42
+ | - Verifies License with Hardware Device ID |
43
+ | - Decrypts skills to local workspace |
44
+ | - Registers MCP Server to IDE (Antigravity) |
45
+ +-----------------------------------------------+
46
+ ```
47
+
48
+ ---
49
+
50
+ ## 📚 Tài Liệu Hướng Dẫn Nhanh
51
+
52
+ Hệ thống được chia làm hai vai trò vận hành chính. Vui lòng tham khảo tài liệu hướng dẫn chi tiết tương ứng:
53
+
54
+ ### 1. Dành Cho Quản Trị Viên (Admin)
55
+ 👉 Xem tại: **[Hướng Dẫn Triển Khai & Cấp Khóa (Admin)](file:///c:/Users/admin/Documents/Projects/MCP_AI_Agent/base_mcp_ai_agent/docs/admin-guideline.md)**
56
+ * **Nội dung bao gồm**:
57
+ * Các nguyên tắc bảo mật và lưu trữ khóa ngoại tuyến (`master.key`, `bundle.key`).
58
+ * Quy trình build, đóng gói mã hóa AES-256 các Skill thành tệp `.enc` và xáo trộn mã JS bằng `javascript-obfuscator`.
59
+ * Cách publish package lên GitLab Package Registry cá nhân/doanh nghiệp.
60
+ * Hướng dẫn chạy CLI `gen-key.js` để cấp License Key giới hạn theo thời gian và Device ID cho lập trình viên.
61
+
62
+ ### 2. Dành Cho Lập Trình Viên (Developer)
63
+ 👉 Xem tại: **[Hướng Dẫn Cài Đặt & Sử Dụng (Developer)](file:///c:/Users/admin/Documents/Projects/MCP_AI_Agent/base_mcp_ai_agent/docs/developer-guideline.md)**
64
+ * **Nội dung bao gồm**:
65
+ * Cách thiết lập xác thực `.npmrc` để truy cập GitLab Package Registry riêng tư của công ty.
66
+ * Cách lấy Device ID phần cứng thông qua lệnh `npx apt-mcp-agent-setup init`.
67
+ * Lệnh cài đặt tự động AI Agent vào workspace dự án và đăng ký cổng kết nối vào IDE.
68
+ * Kiểm tra trạng thái hoạt động và thời hạn License Key.
69
+ * Cơ chế tự động dọn dẹp (xóa sạch tài nguyên độc quyền) khi License hết hạn.
70
+ * Hướng dẫn sử dụng các Slash Commands nâng cao: `/plan`, `/tdd`, `/debug`, `/verify`, `/to-issues`.
71
+
72
+ ---
73
+
74
+ ## ⚡ Tóm Tắt Quy Trình Phân Phối Trọn Gói (Deploy/Publish)
75
+
76
+ ### Bước 1: Build đóng gói mã hóa (Admin)
77
+ Đảm bảo bạn đã có các file khóa bảo mật trong thư mục `admin/` và version trong `package.json`, `package-lock.json` đã đồng bộ. Phiên bản source chuẩn bị phát hành là `3.5.18`. Chạy:
78
+ ```bash
79
+ npm run deploy
80
+ ```
81
+
82
+ Chọn **3** để build source hiện tại, ký runtime, đóng gói tarball, kiểm tra gói và publish lên npm. Luồng mặc định không yêu cầu đường dẫn JSON nghiệm thu và không tự tăng version. npm có thể yêu cầu đăng nhập hoặc xác thực khi publish.
83
+
84
+ Nếu chỉ build local sau khi đã chọn version, chạy:
85
+ ```bash
86
+ npm run build
87
+ ```
88
+ Lệnh build mã hóa thư mục `.agents/` và `src/templates` thành các file `.enc` trong thư mục `bundle/`, sau đó build mã nguồn JS đã được xáo trộn ra thư mục `dist/`. Nếu `npm run deploy` đã mở từ trước rồi source thay đổi, hãy thoát menu cũ và chạy lại để nạp script mới. Menu cũ tự dừng trước khi build hoặc publish, tránh phát hành với logic version cũ.
89
+
90
+ ### Bước 2: Kiểm tra bản phát hành (Admin)
91
+
92
+ Menu deploy thực hiện publish sau khi package gate pass. Không cần chạy thêm lệnh publish trong `dist/`. Nếu đã đặt biến `APT_RELEASE_ACCEPTANCE`, deploy dùng luồng artifact đã nghiệm thu thay cho build source; bỏ biến đó để dùng luồng mặc định.
93
+
94
+ Quyết định phát hành `3.5.15` và những phần kiểm thử local chưa hoàn tất được ghi tại [ghi chú phát hành](docs/releases/3.5.15.md). Sau publish, người dùng tiếp tục cập nhật bằng một lệnh:
95
+
96
+ ```bash
97
+ npx apt-mcp-agent-setup@latest update
98
+ ```
99
+
100
+ ### Bước 3: Sinh License Key cho Dev/QC/BA/PM (Admin)
101
+ Khi nhận được Device ID từ nhân viên, hãy chạy CLI sinh khóa. Bạn có thể chỉ định một hoặc nhiều Preset ghép nối (Stackable Presets) ngăn cách bằng dấu phẩy:
102
+ ```bash
103
+ # Cấp khóa cho Dev di động Flutter
104
+ node admin/gen-key.js --device <DEVICE_ID> --user "nguyen-van-a" --expires 2026-12-31 --preset mobile-flutter
105
+
106
+ # Cấp khóa tích hợp: Dev React + Quyền quản lý dự án (PM) + Tích hợp thiết kế Figma
107
+ node admin/gen-key.js --device <DEVICE_ID> --user "tran-van-b" --expires 2026-12-31 --preset fe-react,pm,figma
108
+ ```
109
+ Copy chuỗi License Key xuất ra và gửi cho người dùng.
110
+
111
+ ### Bước 4: Cài đặt & Sử dụng (Developer / QC / BA / PM)
112
+ Người dùng không cần cấu hình bất kỳ tệp tin xác thực `.npmrc` nào. Hãy mở terminal tại thư mục gốc dự án và chạy trực tiếp lệnh cài đặt:
113
+ ```bash
114
+ npx apt-mcp-agent-setup@latest install --key <LICENSE_KEY_ĐÃ_NHẬN>
115
+ ```
116
+
117
+ > [!IMPORTANT]
118
+ > **Lưu ý quan trọng**: Luôn mở terminal và chạy lệnh trên tại **thư mục gốc của dự án** bạn muốn cấu hình AI Agent. Không chạy ở thư mục người dùng chung (`~` hoặc `C:\Users\Username`). Mỗi dự án sẽ được cấp một vùng làm việc độc lập chứa các Skill (.agents/) và bộ nhớ (.memory/) riêng biệt để đảm bảo hiệu quả làm việc và bảo mật.
119
+
120
+ Hệ thống sẽ tự động cấu hình môi trường, giải mã các Kỹ năng phù hợp với Preset được cấp trong License Key và tích hợp thẳng vào IDE (Antigravity IDE, Claude Code, Cursor, hoặc VS Code).
121
+
122
+
123
+