feat(private-library): publish skills/kits riêng tư và đồng bộ đa thiết bị, kèm DoD với AgentKit

Revalidate HEAD and deployment status first. Read apps/web/app/lib/releases/release-store.ts and apps/web/wrangler.jsonc, then trace the existing personal-kit API and CLI contracts referenced by #88 and #94; confirm current behavior before changing anything. Map the DoD to implementation and tests, then verify the staging and approved production smoke evidence, including the AgentKit round trip from machine A to B and back.

Mục tiêu và trách nhiệm

Người dùng yêu cầu ngày 19/10/2026: sau khi AgentKit phân tích session và người dùng duyệt bản cải tiến, có thể publish riêng tư lên SkillX, chọn cài một skill hoặc cả kit của mình trên thiết bị khác, rồi tiếp tục chỉnh sửa và publish từ thiết bị đó.

Issue này sở hữu phần thư viện private, product/API/CLI integration và bằng chứng nghiệm thu của SkillX; không viết lại registry, personal-kit composer hay AgentKit installer. Parent liên quan: #34/#35; rollout và các khoảng trống personal-kit API thuộc #88. Tái sử dụng #54/#55/#56 và phần đã triển khai trong #83/#94. Đối ứng trực tiếp: AgentKit #2640, dưới #2589 và #2281.

SkillX không phân tích hay lưu nguyên session. AgentKit giữ evidence nhạy cảm, đánh giá và cài đặt; SkillX giữ package/revision đã được người dùng cho phép gửi, authorization, lineage, version pins và audit.

Baseline đã kiểm tra

Kiểm tra main tại 5fc3077d2aa539a717fe69e259daf8648d9ccf6d ngày 19/10/2026:

• apps/web/app/lib/releases/release-store.ts tạo package mới với literal 'public'. Có cột visibility và private read gate không đồng nghĩa đã có luồng user publish private hoàn chỉnh.
• apps/web/wrangler.jsonc đặt SKILLX_RELEASES_API=1, SKILLX_PERSONAL_KITS_API=0. Đây là cấu hình repo, chưa xác nhận runtime production có override hay không.
• Personal-kit API đã có immutable revisions, composition, CAS/If-Match, proposals/review/activate và lock; #88 xác nhận nhiều phần đã làm. Không mở lại #55/#56 hoặc triển khai lại phần đã hoàn tất chỉ vì còn thiếu integration.
• Kit API hiện nhận web session hoặc unscoped account API key, từ chối scoped publish key. Release publishing dùng publisher-scoped credential. Review session-derived proposals yêu cầu interactive web session. Phải xử lý có chủ đích sự khác nhau này, không giả định một token hiện chạy được mọi endpoint.
• Private release reads đi qua entitlement gate. Trải nghiệm owner publish xong phải đọc được tài sản của mình mà không cần sửa DB bằng tay cần được chốt/test.
• Foundation provenance có #100; consumer là AgentKit #2623, liên quan #2627. Secret scanner có follow-up #105; không bỏ qua lỗi encoding khi công bố private publishing an toàn.

Revalidate HEAD và trạng thái triển khai trước khi bắt đầu; issue đóng hoặc PR mở không phải bằng chứng production GO.

Mô hình và contract cần hoàn thiện

Đối tượng	Semantics
Standalone skill package	Cây tài nguyên do người dùng chọn: SKILL.md, references/scripts/assets và dependencies hợp lệ; immutable release, digest, visibility và owner
Personal kit	Composition/pins + overlays/lineage + metadata đủ sửa tiếp; không sao chép foundation được bảo vệ thành public payload
Thư viện cá nhân	Chỉ mục riêng của tài khoản cho cả hai loại; lựa chọn cài từng mục hoặc kit; không phải public search có thêm bộ lọc giao diện
Hồ sơ cài đặt tối thiểu	Lựa chọn assets và runtime/project scope; AgentKit sở hữu projection cục bộ, không đồng bộ secrets hoặc đường dẫn máy

Không ép skill độc lập thành kit một phần tử để che phần private registry còn thiếu. Không tạo registry/storage thứ hai. Server trả identity/version/revision/digest/visibility/compatibility cần thiết để client chọn và pin rõ ràng; không ngầm cài latest.

Private publishing và authorization

Thêm lựa chọn visibility vào contract/API/CLI đang có, ví dụ skillx release publish ... --visibility private là giao diện đề xuất, phải chốt theo CLI hiện tại. Luồng tài sản cá nhân mới ưu tiên private. Không làm đổi visibility của package cũ chỉ vì publish version mới; giữ tương thích luồng public legacy bằng policy/version rõ ràng. Tuyệt đối không fallback từ private sang public khi endpoint/flag/auth không hỗ trợ.

Chọn và ghi ADR về owner access: owner-aware entitlement gate hoặc entitlement được tạo atomically khi publish. Dù cách nào, owner đọc/quản lý được tài sản vừa tạo, user khác không có quyền, và publisher suspended/quarantined/revoked vẫn bị chặn theo policy. Quyền đọc base có license/entitlement độc lập với quyền sở hữu kit.

Chuẩn hóa capability/scoped auth cho library read, private download, publish và kit writes; giữ đường compatibility có tài liệu cho unscoped key hiện tại, không cấp admin hoặc quyền toàn tài khoản âm thầm. Không phát minh OAuth mới nếu cơ chế đăng nhập/token hiện có đủ; credential của máy A/B phải có thể thu hồi độc lập.

Nội dung bắt nguồn từ session

Dùng skillx.kit-proposal/v1 và review policy hiện hữu: validate → proposed → user review → activate. Giữ session-derived origin xuyên các revision/fork/rebase; không cho client đổi nhãn thành manual để bỏ kiểm tra. Server không nhận raw transcript, session IDs/ranges, credentials, local paths hay code vô tình trích từ transcript.

Mặc định chỉ gửi thay đổi được duyệt + pins + metadata tối thiểu. Evidence summary tổng hợp phải opt-in, có giới hạn và không chứa nội dung nguồn. Private không có nghĩa được miễn content scan. Không tuyên bố scan có thể nhận diện mọi secret; kiểm thử các lớp dữ liệu nguy hiểm đã xác định, từ chối input không thể kiểm tra an toàn.

Review web-session-only hiện tại không được hạ xuống approved=true trong body. Luồng từ CLI phải mở/đi theo bước web review đang được hỗ trợ hoặc có thiết kế approval proof riêng được duyệt. Publish/activate không phải quyền tự phê duyệt của agent.

Definition of Done

A. Private skills và kits

• SX-D01: Người dùng tạo standalone skill private qua API và CLI được hỗ trợ, gồm tài nguyên lồng nhau, rồi publish version tiếp theo. Payload/response/schema/help khớp nhau; unknown visibility bị từ chối; new-private path không ghi public dù gặp lỗi.
• SX-D02: Visibility không bị thay đổi ngầm khi publish release mới. Existing public packages/clients vẫn hoạt động theo migration policy. Public → private không được quảng bá là xóa bản sao đã tải trước đó; private → public cần chấp thuận riêng và kiểm tra license/derivative.
• SX-D03: Owner có thể liệt kê, đọc, tải và quản lý tài sản private vừa publish mà không cần admin sửa DB. Có tests owner, user khác, anonymous, expired/revoked credential, publisher suspended và entitlement bị thu hồi. Access tới base private/paid vẫn được kiểm tra riêng.
• SX-D04: Personal kits lưu và trả đầy đủ pins, overlays, lineage, exclusions và composition metadata để máy B có thể sửa/rebase/publish tiếp. Tái dùng golden vectors #94; giữ digest của documents cũ khi optional fields vắng mặt.
• SX-D05: Client/server có matrix auth/capabilities rõ ràng. Từ chối key sai scope, cross-publisher write và tài khoản không sở hữu kit; lỗi không âm thầm mở rộng quyền hoặc chuyển thành anonymous/public. Có đường nâng cấp tương thích cho callers hiện tại.

B. Thư viện cá nhân và quyền riêng tư

• SX-D06: Có API thư viện cá nhân phân trang, chỉ trả tài sản caller được phép thấy, lọc skill/kit và tên, kèm identity/visibility/version hoặc revision/digest/state. CLI và dashboard có đường sử dụng được; agent-facing API/MCP đã quảng bá dùng chung gate, không truy cập DB tắt.
• SX-D07: UI hỗ trợ publish hoặc quản lý visibility/revisions của tài sản và chọn cài skill lẻ/kit. Endpoint chưa bật phải hiện unavailable và bước xử lý đúng, không có nút báo thành công khi API trả 404.
• SX-D08: Private bytes lẫn metadata nhạy cảm không lộ qua public search, suggestions, Vectorize, leaderboard, sitemap, profile/feed, MCP, preview/OG, cache/CDN hoặc logs. Kiểm thử biết slug/digest trực tiếp vẫn không đọc được; không chỉ ẩn trên giao diện.
• SX-D09: Mọi manifest/files/artifact/download URL tái kiểm tra access và release state. Signed URLs có TTL, bị chặn sau revoke/quarantine theo contract; shared digest không làm một public package cấp quyền đọc private package. Không có public R2 URL/redirect vượt gate. Private responses dùng cache policy cách ly rõ ràng.
• SX-D10: Private-to-public transition/derivative không phát tán foundation paid/private, kể cả patch context hoặc preview. Giữ shared-alias fork policy; không nới policy trong #88 để làm test xanh.

C. Review, integrity và an toàn

• SX-D11: Session-derived proposal đi qua validate/review/activate, lưu consent đúng digest + permissions + visibility; rejected/quarantined proposal không trở thành effective. Token publish không tự đóng vai người duyệt; origin không mất qua lineage hoặc import.
• SX-D12: Schema/content scan từ chối raw-session fields, secret fixtures, absolute paths, traversal, symlink/hardlink, hidden executable additions và tài nguyên quá giới hạn. Bao gồm UTF-16/BOM/encoding tests liên quan #105. Errors/logs/audit không echo nội dung bị chặn; package scripts hợp lệ chỉ được lưu, không thực thi khi upload/read.
• SX-D13: Version/revision bất biến; retry cùng idempotency key và payload trả cùng kết quả; cùng key khác payload bị từ chối. Partial R2/D1 writes, request bị ngắt và retry không tạo release hiển thị thiếu tài nguyên hoặc revision trùng.
• SX-D14: CAS/ETag/If-Match giữ semantics hiện tại: stale update trả 409/412 đúng contract, không ghi đè revision của máy khác. Có test hai writers song song, canceled review và rollback; không last-writer-wins.
• SX-D15: Foundation @agentkit/* mirrors được chấp nhận chỉ qua publisher/provenance hợp lệ theo #100 và client #2623; không tự nâng trust thành signed-kit trust. Old pinned base vẫn resolve theo lifecycle/entitlement policy; malformed provenance và digest mismatch bị từ chối.

D. Vòng nhiều thiết bị và rollout

• SX-D16: Với AgentKit build thật, máy A publish private standalone skill và personal kit r1; máy B sạch đăng nhập, liệt kê được tài sản của owner, chọn từng mục, sync đúng revision và xác minh effective digests giống A. Không cần foundation local và không cần admin chỉnh entitlement thủ công.
• SX-D17: Máy B sửa kit đã sync và publish r2; máy A preview/nhận r2 hoặc thấy conflict khi đã sửa riêng. Có rebase foundation và rollback về revision trước. Bằng chứng phải chứng minh khả năng authoring round-trip, không chỉ download/read-only projection.
• SX-D18: Hai tài khoản thử nghiệm và hai credential/thiết bị chứng minh cách ly private data; thu hồi credential máy B không làm máy A mất quyền ngoài policy. Không đồng bộ sessions, secrets, OS paths, symlinks hay quyền thực thi đã cấp trên máy A.
• SX-D19: Offline, API tắt, token hết hạn, source revoked/quarantined, missing base và incompatible runtime được trả trạng thái machine-readable đúng; client giữ bản đang chạy hoặc từ chối theo policy, không tự tải latest/cho truy cập vì cùng digest và không bypass auth qua cache.
• SX-D20: Rollout theo #88 có D1 backup, migration/rollback được thử, signing keys/rate limits/storage guards hợp lệ, kiểm tra runtime flags thay vì chỉ đọc repo config. Chạy staging và smoke production được phê duyệt bằng test accounts; health/readiness, docs, API/CLI contract, dashboard states và receipts cập nhật. Fake-only/flag-on không đủ đóng issue.

Ma trận nghiệm thu chung với AgentKit #2640

Ca	Kết quả bắt buộc
Cải tiến từ session	Candidate được người dùng duyệt, không gửi transcript; source origin/review proof còn nguyên
Skill private độc lập	Toàn bộ cây tài nguyên được publish/read/sync riêng lẻ, không cần kit trung gian
Personal kit	Delta + exact bases dựng lại đúng, không leak upstream
Máy A → máy B → máy A	r1/r2 được pin và chỉnh sửa tiếp; concurrent write có conflict rõ
Review từ chối / regression	Không tự activate hoặc publish candidate; quality verdict do AgentKit tạo, SkillX không biến một counter tự khai thành chứng nhận
Thu hồi / quarantine	Read/download bị chặn qua mọi bề mặt và URL đã cấp theo contract
Mất mạng / bị ngắt	Retry idempotent, không có tài sản half-published hoặc đổi private thành public
Khôi phục	Exact revision/digest và metadata tác giả đủ để rollback/rebase tiếp

Bằng chứng và điều kiện đóng

Bắt buộc có các PR đã merge, SHA chính xác hai repo, CLI build/deployment/schema IDs và bảng SX-Dxx → test/command → environment → result → artifact. Kèm receipts đã lọc của A/B, authorization negative matrix, digest comparisons, CAS/retry/rollback, migration và production smoke. Mọi mục chưa có bằng chứng giữ unchecked; không suy từ #55/#56 closed rằng rollout đã xong.

Không chứa secrets hoặc session contents trong issues, CI logs, benchmark artifacts hay analytics. Mã hóa đầu cuối không thuộc issue này; không quảng bá private registry là E2EE.

Thứ tự triển khai

1. Chốt contract visibility/owner access/scopes và private-library API trong registry hiện có; thêm negative tests trước.
2. Hoàn thiện API/CLI/dashboard cho private standalone skill, nối personal kits/proposal review đang có; xử lý #88/#100 và scanner blockers.
3. Nối AgentKit #2640, chạy round-trip bằng build thật, rồi rollout được phê duyệt và đối chiếu DoD.

Ngoài phạm vi: AI phân tích raw sessions trên SkillX, huấn luyện trên dữ liệu riêng, tự publish/approve, marketplace settlement, tổ chức ACL phức tạp, registry thứ hai, viết lại Go installer hoặc runtime script execution trên server.