nccgs 2.1.0 → 2.1.1

package/docs/ASSET-PRODUCTION-GRAPHIFY-PLAN.md

@@ -0,0 +1,230 @@
+# NCCGS Asset Production and Graphify Update Plan
+
+Date: 2026-10-31 (Asia/Saigon)
+
+Status: Implementation plan. The two feature directions are agreed; runtime changes, installation, qualification and publication have not started under this plan.
+
+## 1. Agreed scope
+
+Update NCCGS in two areas:
+
+1. Add focused asset-production support through existing studio responsibilities: an art-direction brief, an asset manifest and production/import/visual-QA checklists.
+2. Use an existing project-level Graphify setup when present and usable. Synchronize its selected inputs after NCCGS changes them. If the project has no Graphify setup, skip this integration without installing anything.
+
+NCCGS remains New Claude Code Game Studio and targets Claude Code. Archify remains an optional tool in the shared project workflow and is outside this change. Do not import the complete external game-dev skill catalog or introduce another orchestrator.
+
+The implementation choices below make the agreed scope concrete. They describe proposed behavior and files, not commands or settings already implemented in NCCGS.
+
+### Shared-workflow boundary clarified on 2026-10-31
+
+The outer sequence stays PO + ChatGPT/Codex brainstorm -> confirmed approach -> English prompt -> Claude Code executes through NCCGS -> PO + ChatGPT/Codex review. NCCGS's whole internal process is part of the Claude step. Internal planning, orchestration, reviews and task closure remain its own responsibility within the approved assignment. Do not require compatibility migration or native external-review/PO gates merely to reproduce the outer sequence. Internal DONE can return a candidate while outer review remains pending. Preserve existing native obligations until an actual blocker is assessed and a correction authorized.
+
+Graphify is the common integration contract: both layers use the same effective project configuration, corpus/exclusions, configured graph location, backend/resource limits and freshness record. Both account for their selected source changes. NCCGS uses existing project setup or skips; it does not create a second graph, bootstrap one or invoke shared install policy as a side effect.
+
+## 2. Current baseline and relevant findings
+
+The inspected source is unpublished NCCGS 2.1.0. Published 2.0.0 and frozen qualification records remain unchanged. New behavior requires its own verification; previous native execution evidence does not transfer automatically.
+
+| Existing area | Inspected location | Consequence for this change |
+|---|---|---|
+| Authority and extension rules | `NCCGS/MEMORY.md`, `.claude/nccgs/constitution.md`, `docs/ARCHITECTURE.md` | Extend existing responsibilities and preserve acceptance authority. |
+| Art ownership | `.claude/nccgs/agent-library/nccgs-art-direction-lead.md`, `nccgs-technical-artist.md`; existing Unity content specialist | Reuse these roles; do not make additional specialists mandatory. |
+| Asset audit | `.claude/skills/asset-audit/SKILL.md` | Add assignment-specific guidance through its underlying protocol/reference route. |
+| Selective shared guidance | `.claude/nccgs/packages/ponytail/README.md` | Follow the existing on-demand package pattern without mixing art guidance into Ponytail. |
+| Project configuration and templates | `scaffold/.nccgs/project.yaml`, `scaffold/.nccgs/templates/` | Reuse existing configuration and scaffold mechanisms. |
+| Context and handoff | `protocols/context-packets.md`, `protocols/agent-contract.md`, `protocols/standalone.md`, `templates/context-packet.yaml` | The coordinator owns retrieval and synchronization; bounded workers keep existing limits. |
+| Session hooks | `hooks/session-start.mjs`, `hooks/session-stop.mjs`, `settings.fragment.json` | Keep hooks short; do not perform model extraction inside a stop hook. |
+| Snapshot and source guards | `tools/gates.mjs`, `tools/inputs.mjs`, `pipeline.json` | Root `graphify-out/` is currently included in source snapshots. Refresh timing matters. |
+| Generated policy | `tools/compile-policy.mjs`, agent library, workflow catalog | Edit source templates/protocols and regenerate generated files. |
+| Distribution lifecycle | `scripts/install.mjs`, `doctor.mjs`, `uninstall.mjs`, `validate.mjs` | Ship and diagnose the additions without taking ownership of an existing Graphify installation. |
+
+In particular, `inputs.json` currently permits dedicated build output directories and specific Unity-generated metadata, not an arbitrary Graphify exclusion. This plan does not weaken that rule or add a blanket `graphify-out` snapshot exclusion.
+
+## 3. Asset-production support
+
+### Deliverables
+
+Create a small on-demand package and two project templates. Adapt useful upstream material from `create-game-assets`; pin the reviewed upstream commit and selected files during implementation. Keep its applicable license, attribution and adaptation notice.
+
+| Deliverable | Purpose | Existing owner |
+|---|---|---|
+| Art-direction brief | Record visual constraints, target display, asset scale and the accepted reference | Art Direction / accountable coordinator |
+| Asset manifest | Track required assets and variants, technical specifications, provenance and approval status | Technical Artist / Unity content specialist |
+| Production checklist | Move from representative reference to a consistent asset family | Assigned art/content owner |
+| Import and visual-QA checklist | Check technical fit and actual appearance in the game | Technical Artist, relevant Unity specialist and QA |
+
+Use these only for relevant asset assignments. Preserve existing briefs, approved style and user-owned source art. Distinguish technical checks from aesthetic approval. Image generation is an optional production method, not a dependency or a completion claim.
+
+The first implementation will not vendor the upstream image-processing scripts or add Python/Pillow dependencies to NCCGS. Existing approved tools and official Unity Skills handle operations. Add a helper later only when a real assignment demonstrates a repeatable gap.
+
+### Acceptance
+
+- An asset assignment can produce a usable brief and manifest without an image-generation tool.
+- The manifest distinguishes placeholders, candidates, technically checked assets and assets with the required visual acceptance. These labels never create approval by themselves.
+- Checks cover the approved specifications and in-context inspection; a schema-valid manifest alone cannot satisfy visual acceptance.
+- Unrelated programming tasks do not load the package, create asset documents or activate art specialists.
+
+## 4. Graphify policy: use an existing project setup
+
+### Detect project adoption before checking readiness
+
+The policy is **auto-existing**, with an explicit project/shared-workflow disable taking precedence. This name describes the intended NCCGS policy; it is not a native Graphify option.
+
+A globally installed `graphify` executable or `graphifyy` package is not sufficient evidence that the current project uses Graphify. Accept explicit shared-workflow configuration or validated project artifacts identifying this target's graph/corpus. Configuration files such as `.graphifyrc` or `.graphifyignore` are discovery signals, not proof that a usable graph exists.
+
+Resolve the actual project/subproject root and configured graph location. Preserve existing paths and ownership; do not create a second graph or assume that a nearby graph belongs to this project.
+
+| Observed project state | NCCGS behavior |
+|---|---|
+| Graphify explicitly disabled | Skip use and refresh; preserve all existing files. |
+| No project Graphify setup, including a machine with only a global CLI | Skip quietly in ordinary work; status/doctor may report `not applicable`. No Graphify command, installation or new project configuration. |
+| Project setup and usable current graph | Use focused retrieval, then inspect original sources for decisions and edits. |
+| Project setup and stale graph | Refresh the relevant supported inputs at a safe boundary within existing permissions and budgets. |
+| Project setup but executable, initial graph or semantic backend unavailable | Report the specific unavailable/pending capability and use direct source inspection. No installation, initial full-corpus bootstrap or new provider setup. |
+| Incompatible schema/version or uncertain graph ownership | Do not mutate or trust the graph; report the reason and use sources directly. |
+
+No Graphify software upgrades, package-extra installs, assistant-skill registration, new git hooks, watcher startup or hosted-service adoption belong to this adapter. A shared workflow can manage installation under its own separately authorized policy; NCCGS does not invoke that policy as a side effect of discovery.
+
+### Minimal configuration
+
+Resolve the existing shared-workflow/project Graphify configuration as the single effective integration policy. Do not add an independently editable NCCGS override for activation, corpus, backend or graph location. The adapter may retain a configuration identity/reference for validation; it must not become another policy authority. If no shared-workflow binding exists, use the existing project Graphify configuration directly under the same existing-setup-or-skip rule.
+
+Graph/corpus paths, exclusions and backend settings keep their current owner. Machine-local executable discovery must not enable a disabled project or silently select another provider. No new configuration key or parser is claimed to exist.
+
+## 5. Graph freshness and synchronization
+
+### Separate code freshness from document freshness
+
+The reviewed Graphify documentation distinguishes code refresh from semantic document refresh. `graphify update` refreshes code; it does not reprocess changed documents. Watch mode can mark semantic changes as pending instead of completing them. Therefore a successful code update cannot establish that a new NCCGS Markdown document is indexed.
+
+Implement a version-aware adapter around the project's existing Graphify capability:
+
+- Use its supported incremental code path for code changes.
+- Use its supported incremental semantic path for documents, with the already configured backend and allowances. The documented headless `extract` path can be incremental, but exact behavior must be qualified for the supported installed version.
+- If semantic refresh cannot run under existing controls, retain pending document paths and disclose stale coverage. Do not select credentials, buy capacity or launch an unmanaged assistant session.
+
+Do not invoke the upstream `/graphify` skill wholesale inside an NCCGS worker: its orchestration may conflict with NCCGS reservations, worker depth and budget controls. Any necessary assistant-owned work must follow the existing Claude Code lifecycle.
+
+### Corpus and change detection
+
+Honor the existing project corpus and exclusions. NCCGS does not index every file it creates. Prefer relevant source, tests and canonical design/decision documents. Exclude graph outputs, temporary reports, build/cache directories and mutable synchronization state from the corpus to prevent self-triggering loops. An intentionally excluded file remains excluded.
+
+Compare content fingerprints, including new, edited, renamed and deleted files and uncommitted changes. Reconcile a worker's changed-file list with actual corpus changes, because shell and Editor/MCP operations can bypass text-edit hooks. Track code and semantic completion separately. Failed or omitted semantic chunks must remain pending.
+
+### Lifecycle and one update owner
+
+1. **Before retrieval:** inspect project adoption, readiness, relevant input hashes and coverage. Refresh stale context when allowed; otherwise use original sources with a visible limitation.
+2. **During an editing batch:** accumulate changed paths. Do not rebuild after every save.
+3. **After writers settle:** the coordinator invokes one bounded refresh before the next graph-dependent handoff or source snapshot used for verification/review.
+4. **At handoff:** record `current`, `partial`, `stale`, `unavailable` or `skipped`, with pending paths and the next action when relevant. Only a successful refresh against the current relevant bytes may report `current`.
+
+Use the shared updater when it exposes a compatible supported interface. That runner is not assumed to exist today: NCCGS also needs a small adapter to the existing installed CLI for supported versions. Both routes use one update owner for a graph. If an external watcher/update is active and coordination cannot be established, defer mutation and keep the pending status; do not kill another process or write concurrently.
+
+The shared workflow applies the same contract to its own selected decision, task and prompt writes before graph-dependent dispatch. NCCGS applies it after its implementation batches and before handoff. They use one logical graph/freshness record per configured corpus. A private adapter receipt may reference the common result but cannot independently declare different coverage current. Handoff reports link the same configuration/input identity and pending paths.
+
+Long refreshes use owned processes with finite deadlines and output limits. Do not detach, start a daemon or conceal backend work in a short session hook. A refresh is context maintenance with declared writes, not a verification command pretending the source stayed unchanged.
+
+### Preserve review and acceptance integrity
+
+Finish refreshes that write inside the source snapshot before recording implementation/review evidence. Do not refresh while an independent reviewer holds that snapshot. A later source or in-snapshot graph change invalidates prior evidence under the existing rules; do not mask it with a broad exclusion or rewrite a frozen verdict.
+
+Keep the shared freshness record at the project's existing accepted derived location, accessible to both layers. If none exists, agree one during adapter design. `.nccgs/context/` may hold NCCGS attempt references, but not a competing authoritative freshness record. Exclude derived records from the Graphify corpus. Final operational notes should use existing excluded evidence/handoff locations, preventing an endless index-report-index cycle.
+
+Read-only assignments may inspect an existing current graph but must not rebuild it when their write authority forbids that mutation. Bounded repair workers continue following their exact packets; the coordinator handles context refresh outside the repair invocation.
+
+Index synchronization does not replace game verification or add a universal subjective gate. Failed optional context maintenance must remain visible separately from the technical outcome. If a task explicitly requires an up-to-date graph as an acceptance criterion, that criterion remains unsatisfied until verified.
+
+## 6. Proposed implementation files
+
+Paths below are relative to `NCCGS/`. New paths are proposals; confirm their final names against the implementation diff.
+
+| Area | Existing files to change | Proposed additions |
+|---|---|---|
+| Asset guidance | `.claude/nccgs/protocols/agent-contract.md`, `.claude/nccgs/constitution.md`; relevant art/content role source files | `.claude/nccgs/packages/asset-production/README.md`, `production-checklist.md`, `manifest.json`, `LICENSE`, `NOTICE.md` |
+| Project asset templates | Existing scaffold installation path; no generated example art | `scaffold/.nccgs/templates/art-direction-brief.md`, `asset-manifest.json` |
+| Graphify adapter | Existing policy parsing utilities and `scripts/doctor.mjs` | `.claude/nccgs/tools/graphify.mjs`, `.claude/nccgs/protocols/graphify-context.md` |
+| Coordinator integration | `protocols/context-packets.md`, `protocols/standalone.md`, affected compatibility procedures, `tools/handoff.mjs` and coordinator lifecycle boundaries in `tools/task.mjs` as needed | Focused read-only inspection and bounded synchronization entry points, names finalized during implementation |
+| Session visibility | `hooks/session-start.mjs`, `hooks/session-stop.mjs` only for short status/pending notices | No extraction hook or new background service |
+| Context and reports | `scaffold/.nccgs/templates/context-packet.yaml`; affected existing handoff/report templates without rewriting their execution-policy ownership | Optional graph provenance/freshness reference; no mandatory graph fields for projects without it |
+| Configuration | Existing project/shared Graphify configuration resolution | Configuration identity/reference only; no independently editable NCCGS Graphify override |
+| Packaging and attribution | `scripts/validate.mjs`, install/doctor/uninstall handling where necessary, `THIRD_PARTY_NOTICES.md`, existing package notice index | Focused package/template validation |
+| Documentation | `docs/ARCHITECTURE.md`, `MEMORY.md`, `README.md`, `UPGRADING.md`, `CHANGELOG.md` | `docs/ASSET-PRODUCTION.md`, `docs/GRAPHIFY-INTEGRATION.md` |
+| Tests | Existing framework, lifecycle, installer and uninstaller suites | `tests/asset-production.test.mjs`, `tests/graphify-integration.test.mjs` |
+
+Do not directly patch generated role/model pins or generated workflow wrappers. Use their authoritative sources and `policy:build`. Leave official Unity Skills unchanged. No modification to snapshot exclusions or acceptance thresholds is planned.
+
+## 7. Implementation sequence
+
+| Phase | Work and stopping point | Validation |
+|---|---|---|
+| 1. Freeze contracts | Pin upstream asset files/licenses; establish supported installed Graphify capabilities, project discovery rules and fixture corpus. Resolve the internal adapter interface. | Review the allowed writes, provider path, state matrix and snapshot timing before runtime edits. |
+| 2. Add asset support | Add the focused package/templates and assignment routing through existing roles. | Exercise a small artist-handoff example without generation tools; confirm unrelated assignments stay unaffected. |
+| 3. Add Graphify support | Implement read-only discovery, freshness tracking, single-owner refresh and pending/fallback reporting. Connect coordinator boundaries. | Run behavioral fixtures for absence, code updates, semantic updates, failure and concurrent changes. |
+| 4. Integrate distribution | Update managed-file recognition, doctor diagnostics, docs, attribution and generated outputs. | Fresh install/update/uninstall in disposable fixtures; preserve custom files and externally owned Graphify data. |
+| 5. Qualify and package | Run relevant regression, inspect the exact archive and obtain fresh independent review. | Complete the cases below; document remaining external/provider limitations. Keep publication separate. |
+
+Use one small change set per feature area plus distribution integration so each change remains reviewable. Choose release numbering during release preparation; do not silently promote the unpublished candidate or republish frozen archives.
+
+## 8. Acceptance scenarios
+
+| ID | Scenario | Observable result |
+|---|---|---|
+| AP-01 | An approved asset brief already exists | Its style and constraints are retained; the new template does not invent a redesign. |
+| AP-02 | Artist handoff without an image-generation tool | A coherent brief, manifest and relevant checks are produced; no tool installation or fabricated art approval. |
+| AP-03 | An asset violates its required dimensions/alpha or fails in-game readability | The appropriate technical/visual condition remains unresolved despite valid JSON. |
+| AP-04 | An ordinary code fix | No asset package bulk-read, new asset files or mandatory art-role dispatch. |
+| GF-01 | No project Graphify setup | No Graphify process, installation, graph directory or optional state file is created. |
+| GF-02 | Global CLI exists but project has not adopted Graphify | Same skip behavior; machine installation alone does not activate integration. |
+| GF-03 | Project/shared policy disables an existing setup | No queries or refresh; existing graph and external settings remain intact. |
+| GF-04 | Correct current graph exists | Scoped retrieval refers to this corpus; precise claims still inspect original sources. |
+| GF-05 | Code changes without a commit | The change is detected and the code graph refreshed before graph-dependent reuse. |
+| GF-06 | NCCGS creates or edits an indexed Markdown document | Semantic processing is performed and checked; a code-only receipt cannot mark documents current. |
+| GF-07 | Indexed source is renamed/deleted | Refresh removes or updates stale source references; the old content is not silently retained as current. |
+| GF-08 | Several writes form one batch | One settled update handles the batch; no model request per file save. |
+| GF-09 | Semantic chunk fails or backend/budget is unavailable | Affected documents remain pending, original sources remain available, and no provider or allowance is invented. |
+| GF-10 | Source changes during a refresh | Hash reconciliation prevents a false current status; the new version remains pending. |
+| GF-11 | Another updater owns the graph | No concurrent writer, process termination or false success; synchronization is deferred visibly. |
+| GF-12 | Graph is for another root, malformed or unsupported | No mutation or trust; direct-source fallback with the concrete reason. |
+| GF-13 | Graph outputs and sync receipts change | They do not re-enter the input corpus and trigger endless extraction. |
+| GF-14 | Refresh writes a root `graphify-out/` | It completes before the reviewed snapshot; a later mutation is still detected by the existing source guard. |
+| GF-15 | Audit/review or bounded repair has restricted writes | No new mutation/shell privilege; coordinator or direct-source fallback respects the current mode. |
+| GF-16 | Shared-workflow author changes a selected decision/prompt; NCCGS later changes selected code/documents | Both use the same configuration, graph and freshness record; each batch is refreshed or remains visibly pending before graph-dependent handoff. |
+| GF-17 | An adapter cache disagrees with project configuration or another layer owns an active refresh | Project configuration prevails; no second graph, independent current claim or concurrent writer. |
+| DIST-01 | Update an existing customized NCCGS project | Existing execution obligations, settings, custom templates, history and spent budgets survive. |
+| DIST-02 | Uninstall NCCGS after this addition | Owned unchanged additions can be removed; project asset documents and externally owned Graphify installation/config/graphs remain. |
+
+Use a fake Graphify executable only to test adapter behavior, failure handling and command boundaries. Add a real CLI qualification against a disposable supported corpus when available. A stub that fabricates semantic nodes does not prove real document extraction. Any claim about Claude Code orchestration requires an actual fresh Claude Code run; framework tests and Codex maintenance do not provide it.
+
+Planned maintainer checks are `npm run policy:build`, `npm run policy:check`, `npm run validate`, focused Node test files, the required `npm test` regression and `npm pack --dry-run`. Run them during implementation, not as proof that this planning-only change implemented the features.
+
+## 9. Scope limits and recovery
+
+- Preserve task/model/execution policies and evidence thresholds. No new roles, compulsory multi-agent chain, global Graphify hooks or Archify dependency.
+- Install/update owns only its managed NCCGS additions. Project production documents and existing external tools keep their current ownership.
+- Preserve the last usable graph on failed publication where the supported Graphify route permits it. Always retain a failed/pending receipt; do not promise recovery behavior that the installed tool does not supply.
+- Stop at partial semantic coverage, unknown backend allowance or incompatible output behavior rather than inventing current context or spending a new budget.
+- Keep new source work separate from frozen evaluations, contaminated CP0 and exact published release archives.
+
+## 10. Source references
+
+### NCCGS baseline
+
+- [Portable decisions](../MEMORY.md)
+- [Architecture](ARCHITECTURE.md)
+- [Release status and evidence boundaries](RELEASE-STATUS.md)
+- [Existing shared guidance pattern](../.claude/nccgs/packages/ponytail/README.md)
+- [Context packet protocol](../.claude/nccgs/protocols/context-packets.md)
+- [Snapshot implementation](../.claude/nccgs/tools/gates.mjs)
+- [Canonical input/output controls](../.claude/nccgs/tools/inputs.mjs)
+
+### External references reviewed for this proposal
+
+- [Game asset production skill](https://github.com/gamedev-skills/awesome-gamedev-agent-skills/blob/main/skills/disciplines/create-game-assets/SKILL.md)
+- [Game-dev skills repository and licensing](https://github.com/gamedev-skills/awesome-gamedev-agent-skills)
+- [Graphify official repository](https://github.com/Graphify-Labs/graphify)
+- [Graphify incremental updates](https://docs.graphify.com/open-source/features/incremental-updates)
+- [Graphify documents and media](https://docs.graphify.com/open-source/features/documents-and-media)
+- [Graphify CLI reference](https://docs.graphify.com/open-source/configuration/cli)
+- [Graphify watcher behavior](https://github.com/Graphify-Labs/graphify/blob/v8/graphify/skills/agents/references/add-watch.md)
+
+These external links identify the reviewed capabilities. Resolve and record exact upstream revisions and the supported installed Graphify version during implementation; no floating upstream release is adopted by this plan.

package/docs/HUONG-DAN-MIGRATE-VA-SU-DUNG.md

@@ -1,116 +1,117 @@
-# Hướng dẫn cài đặt và sử dụng NCCGS 2.1.0
-
-Mã nguồn tiếp theo: **2.1.0**, chưa phát hành npm; bổ sung lệnh gỡ NCCGS.
-Bản **2.0.0** đã phát hành ngày 28/10/2026 và được giữ nguyên.
-Dùng gói 2.1.0 cục bộ cùng mã SHA-256 đi kèm; việc chuẩn bị không đổi các kênh npm.
-Biên bản operator dừng Editor phải được đưa vào hồ sơ reviewer bằng
-[hướng dẫn bằng chứng Editor](EDITOR-SESSION-EVIDENCE.md).
-Kiểm thử tính năng gỡ là kiểm thử framework; không được tính thành một lượt
-Claude Code/Unity mới. Các bằng chứng cũ vẫn gắn với đúng gói đã kiểm chứng.
-Xem [trạng thái phát hành](RELEASE-STATUS.md).
-
-## Cài mới vào bản sao dự án
-
-Cần Node.js 18+, Claude Code và Unity project có Assets, Packages, ProjectSettings.
-Chức năng điều khiển Unity cần thêm Editor/CLI phù hợp. Thay đường dẫn ví dụ bằng
-dự án của bạn; đọc kết quả xem trước rồi mới áp dụng:
-
-```powershell
-$NccgsArchive = "D:\path\to\nccgs-2.1.0.tgz"
-npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject" --dry-run
-npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject"
-npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\UnityProject"
-```
-
-Dùng đúng gói cục bộ và SHA-256 đã ghi; các kênh npm không chọn gói chưa phát hành này.
-Cài mới mặc định dùng Claude Code standalone, không yêu cầu Astra/Fable. Dự án cũ
-vẫn giữ nghĩa vụ đã cấu hình; không tự bỏ một bước duyệt chỉ vì cài gói mới.
-
-## Dự án đã cài NCCGS
-
-Sao lưu toàn bộ dự án và dừng phiên đang chạy. Dùng `update` thay `install`, luôn
-xem `--dry-run` trên bản sao trước. Update giữ cấu hình dự án và các tùy chỉnh;
-không dùng `--force` chỉ để xóa cảnh báo. Đọc [hướng dẫn nâng cấp](../UPGRADING.md)
-để xử lý override, task đang mở, chuyển execution policy và khôi phục.
-
-Nâng cấp file và chuyển sang standalone là hai thao tác riêng. Nếu muốn chuyển
-execution policy, dùng `migrate-execution --to standalone --dry-run` theo hướng dẫn.
-Không tự đổi task cũ, xóa lịch sử hay đặt lại số lượt đã dùng. Sau thay hook/cấu hình,
-mở lại phiên Claude Code.
-
-## Gỡ NCCGS khi không còn dùng
-
-Đóng các phiên Claude Code và chờ worker/kiểm tra kết thúc. Từ terminal bên ngoài,
-dùng gói 2.1.0 cục bộ để xem trước rồi gỡ khỏi đúng dự án:
-
-```powershell
-npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject" --dry-run
-npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject"
-```
-
-Có thể gỡ trực tiếp dự án đã cài 2.0.0, không cần nâng cấp trước. Lệnh chỉ xóa
-tệp quản lý còn nguyên bản và tháo hook/import NCCGS; giữ mã game, tệp tùy chỉnh,
-lịch sử task/review/nghiệm thu/chi phí và cấu hình trong `.nccgs`. Các thiết lập
-Claude dùng chung được giữ vì bản cũ chưa ghi nhận quyền sở hữu từng giá trị.
-
-Kết quả trả về mã `id` của bản sao lưu. Để khôi phục, dùng cùng gói với
-`uninstall --project DIR --rollback ID --dry-run`, sau đó bỏ `--dry-run`.
-Khôi phục sẽ bị chặn nếu tệp đã được sửa tiếp. Lệnh không dừng tiến trình, không
-xóa lịch sử và không hoàn lại ngân sách. Xem [chi tiết](UNINSTALL.md).
-
-Nếu launcher bị dừng bất thường, dùng `recover-session --id UUID --dry-run` để
-xem khóa. Chỉ xác nhận `--confirm-process-tree-stopped` sau khi operator đã kiểm
-tra toàn bộ cây tiến trình thực sự dừng; PID chết không đủ để suy ra điều đó.
-Lệnh yêu cầu đúng mã băm xem trước và lý do, lưu nguyên khóa cùng biên bản,
-không chạm khóa task/job/run. Các lệnh agent/migration/policy cũng bị chặn trong
-lúc gỡ. Gỡ bị chặn trước khi sửa tệp được ghi là `cancelled`; lỗi dọn thư mục
-rỗng chỉ là cảnh báo và vẫn trả về mã rollback.
-
-## Bắt đầu một đầu việc rõ ràng
-
-```powershell
-npx --yes --package "$NccgsArchive" nccgs run --project "D:\path\to\UnityProject"
-```
-
-Trong Claude Code, cung cấp mục tiêu, phạm vi, yêu cầu cố định, phần được phép sửa
-và điều kiện nghiệm thu. NCCGS lập hợp đồng công việc, phân loại mức rủi ro, gọi
-worker phù hợp, thu bằng chứng kiểm tra và yêu cầu review độc lập trước khi đóng.
-
-- `/work`: triển khai thay đổi.
-- `/design`: làm rõ thiết kế/yêu cầu; tính năng có design gate phải được review trước.
-- `/audit`: kiểm tra mà không sửa source.
-- `/test`, `/review`: kiểm chứng và review theo hợp đồng.
-- `/status`: xem trạng thái, bằng chứng và việc còn chặn.
-
-Có 47 vai trò trong thư viện, 13 vai trò bật mặc định. FAST yêu cầu Sonnet/medium;
-STANDARD Opus/medium; CONTROLLED Opus/high; reviewer Opus/high. Đây là cấu hình
-mong muốn, không phải bằng chứng model thực chạy. Chỉ gọi chuyên gia khi cần.
-
-Đạt test chưa tự động nghĩa là DONE. Phải có bằng chứng đúng source/contract,
-review hợp lệ và mọi gate áp dụng đều đạt. Nghiệm thu kỹ thuật và quyết định nghiệm
-thu của người dùng được ghi riêng. Một lượt thất bại phải được giữ cùng chi phí,
-nguyên nhân và kết quả sửa lại.
-
-## Hỗ trợ handoff, Unity repair và chia nhỏ task trong NCCGS 2.0.0
-
-Các hỗ trợ đã có từ 2.0.0 được giữ nguyên trong 2.1.0. Coordinator dùng
-`task dispatch-prompt` để lấy prompt và khung bàn giao PARTIAL cho lượt đã đăng ký.
-Worker có thể dùng `task handoff-validate` để phát hiện lỗi cấu trúc trước khi kết
-thúc; repair worker theo giới hạn riêng của gói repair. Sau khi reviewer hoàn thành,
-coordinator dùng `task record-review` để ghi đúng kết luận từ handoff đã ghim,
-qua đầy đủ cổng kiểm tra hiện có. Các lệnh này không tự chấp thuận hay đóng task.
-Xem [cú pháp và giới hạn](HANDOFF-AUTOMATION.md). Dùng source/package mới theo quy
-trình nâng cấp; các lệnh ở trên dùng chính gói 2.1.0 cục bộ chưa phát hành.
-
-Repair cũ giữ nguyên. Gói mới `unity-code` cho sửa/tạo tối đa 8 tệp mã; `unity-editor`
-cho sửa scene/prefab/asset bằng thao tác Editor đã chốt trước. Tệp mới phải được
-Unity import và tạo metadata trước khi worker kết thúc. Không sửa tay GUID hay
-dùng kết quả thao tác Editor thay bằng chứng kiểm thử. Khi thao tác Editor chưa rõ
-đã dừng hay chưa, giữ lượt repair và quyền sở hữu cho tới khi được đối soát; không
-tự chạy lại hoặc hoàn ngân sách. Xem [luồng repair và mẫu gói](BOUNDED-REPAIR.md).
-
-Với task quá lớn cho một lượt, dùng `task slice-preview`, `task slice-plan` và
-`task slice-status` để chia thành các phần có mục tiêu, tệp và phụ thuộc rõ ràng
-trong cùng task. Phần cuối tích hợp toàn bộ điều kiện gốc trước review độc lập.
-Các phần dùng chung ngân sách hiện có; lịch sử, lượt thất bại và các cổng nghiệm
-thu vẫn được giữ. Xem [hướng dẫn chia nhỏ task](TASK-SLICING.md).
+# Hướng dẫn cài đặt và sử dụng NCCGS 2.1.1
+
+Mã nguồn tiếp theo: **2.1.1**, chưa phát hành npm; bổ sung lệnh gỡ NCCGS.
+Bản **2.0.0** đã phát hành ngày 28/10/2026 và được giữ nguyên.
+Dùng gói 2.1.1 cục bộ cùng mã SHA-256 đi kèm; việc chuẩn bị không đổi các kênh npm.
+Biên bản operator dừng Editor phải được đưa vào hồ sơ reviewer bằng
+[hướng dẫn bằng chứng Editor](EDITOR-SESSION-EVIDENCE.md).
+Kiểm thử tính năng gỡ là kiểm thử framework; không được tính thành một lượt
+Claude Code/Unity mới. Các bằng chứng cũ vẫn gắn với đúng gói đã kiểm chứng.
+Xem [trạng thái phát hành](RELEASE-STATUS.md).
+
+## Cài mới vào bản sao dự án
+
+Cần Node.js 18+, Claude Code và Unity project có Assets, Packages, ProjectSettings.
+Chức năng điều khiển Unity cần thêm Editor/CLI phù hợp. Thay đường dẫn ví dụ bằng
+dự án của bạn; đọc kết quả xem trước rồi mới áp dụng:
+
+```powershell
+$NccgsArchive = "D:\path\to\nccgs-2.1.1.tgz"
+npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject" --dry-run
+npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject"
+npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\UnityProject"
+```
+
+Dùng đúng gói cục bộ và SHA-256 đã ghi; các kênh npm không chọn gói chưa phát hành này.
+Cài mới mặc định dùng Claude Code standalone, không yêu cầu Astra/Fable. Dự án cũ
+vẫn giữ nghĩa vụ đã cấu hình; không tự bỏ một bước duyệt chỉ vì cài gói mới.
+
+## Dự án đã cài NCCGS
+
+Sao lưu toàn bộ dự án và dừng phiên đang chạy. Dùng `update` thay `install`, luôn
+xem `--dry-run` trên bản sao trước. Update giữ cấu hình dự án và các tùy chỉnh;
+không dùng `--force` chỉ để xóa cảnh báo. Đọc [hướng dẫn nâng cấp](../UPGRADING.md)
+để xử lý override, task đang mở, chuyển execution policy và khôi phục.
+
+Nâng cấp file và chuyển sang standalone là hai thao tác riêng. Nếu muốn chuyển
+execution policy, dùng `migrate-execution --to standalone --dry-run` theo hướng dẫn.
+Không tự đổi task cũ, xóa lịch sử hay đặt lại số lượt đã dùng. Sau thay hook/cấu hình,
+mở lại phiên Claude Code.
+
+## Gỡ NCCGS khi không còn dùng
+
+Đóng các phiên Claude Code và chờ worker/kiểm tra kết thúc. Từ terminal bên ngoài,
+dùng gói 2.1.1 cục bộ để xem trước rồi gỡ khỏi đúng dự án:
+
+```powershell
+npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject" --dry-run
+npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject"
+```
+
+Có thể gỡ trực tiếp dự án đã cài 2.0.0, không cần nâng cấp trước. Lệnh chỉ xóa
+tệp quản lý còn nguyên bản và tháo hook/import NCCGS; giữ mã game, tệp tùy chỉnh,
+lịch sử task/review/nghiệm thu/chi phí và cấu hình trong `.nccgs`. Các thiết lập
+Claude dùng chung được giữ vì bản cũ chưa ghi nhận quyền sở hữu từng giá trị.
+
+Kết quả trả về mã `id` của bản sao lưu. Để khôi phục, dùng cùng gói với
+`uninstall --project DIR --rollback ID --dry-run`, sau đó bỏ `--dry-run`.
+Khôi phục sẽ bị chặn nếu tệp đã được sửa tiếp. Lệnh không dừng tiến trình, không
+xóa lịch sử và không hoàn lại ngân sách. Xem [chi tiết](UNINSTALL.md).
+
+Nếu launcher bị dừng bất thường, dùng `recover-session --id UUID --dry-run` để
+xem khóa. Chỉ xác nhận `--confirm-process-tree-stopped` sau khi operator đã kiểm
+tra toàn bộ cây tiến trình thực sự dừng; PID chết không đủ để suy ra điều đó.
+Lệnh yêu cầu đúng mã băm xem trước và lý do, lưu nguyên khóa cùng biên bản,
+không chạm khóa task/job/run. Các lệnh agent/migration/policy cũng bị chặn trong
+lúc gỡ. Gỡ bị chặn trước khi sửa tệp được ghi là `cancelled`; lỗi dọn thư mục
+rỗng chỉ là cảnh báo và vẫn trả về mã rollback.
+
+## Bắt đầu một đầu việc rõ ràng
+
+```powershell
+npx --yes --package "$NccgsArchive" nccgs run --project "D:\path\to\UnityProject"
+```
+
+Trong Claude Code, cung cấp mục tiêu, phạm vi, yêu cầu cố định, phần được phép sửa
+và điều kiện nghiệm thu. NCCGS lập hợp đồng công việc, phân loại mức rủi ro, gọi
+worker phù hợp, thu bằng chứng kiểm tra và yêu cầu review độc lập trước khi đóng.
+
+- `/work`: triển khai thay đổi.
+- `/design`: làm rõ thiết kế/yêu cầu; tính năng có design gate phải được review trước.
+- `/audit`: kiểm tra mà không sửa source.
+- `/test`, `/review`: kiểm chứng và review theo hợp đồng.
+- `/status`: xem trạng thái, bằng chứng và việc còn chặn.
+
+Có 47 vai trò trong thư viện, 13 vai trò bật mặc định. FAST yêu cầu Sonnet/high;
+STANDARD Opus/high; CONTROLLED Opus/xhigh;
+leadership Opus/xhigh; reviewer Fable/high. Đây là cấu hình
+mong muốn, không phải bằng chứng model thực chạy. Chỉ gọi chuyên gia khi cần.
+
+Đạt test chưa tự động nghĩa là DONE. Phải có bằng chứng đúng source/contract,
+review hợp lệ và mọi gate áp dụng đều đạt. Nghiệm thu kỹ thuật và quyết định nghiệm
+thu của người dùng được ghi riêng. Một lượt thất bại phải được giữ cùng chi phí,
+nguyên nhân và kết quả sửa lại.
+
+## Hỗ trợ handoff, Unity repair và chia nhỏ task trong NCCGS 2.0.0
+
+Các hỗ trợ đã có từ 2.0.0 được giữ nguyên trong 2.1.1. Coordinator dùng
+`task dispatch-prompt` để lấy prompt và khung bàn giao PARTIAL cho lượt đã đăng ký.
+Worker có thể dùng `task handoff-validate` để phát hiện lỗi cấu trúc trước khi kết
+thúc; repair worker theo giới hạn riêng của gói repair. Sau khi reviewer hoàn thành,
+coordinator dùng `task record-review` để ghi đúng kết luận từ handoff đã ghim,
+qua đầy đủ cổng kiểm tra hiện có. Các lệnh này không tự chấp thuận hay đóng task.
+Xem [cú pháp và giới hạn](HANDOFF-AUTOMATION.md). Dùng source/package mới theo quy
+trình nâng cấp; các lệnh ở trên dùng chính gói 2.1.1 cục bộ chưa phát hành.
+
+Repair cũ giữ nguyên. Gói mới `unity-code` cho sửa/tạo tối đa 8 tệp mã; `unity-editor`
+cho sửa scene/prefab/asset bằng thao tác Editor đã chốt trước. Tệp mới phải được
+Unity import và tạo metadata trước khi worker kết thúc. Không sửa tay GUID hay
+dùng kết quả thao tác Editor thay bằng chứng kiểm thử. Khi thao tác Editor chưa rõ
+đã dừng hay chưa, giữ lượt repair và quyền sở hữu cho tới khi được đối soát; không
+tự chạy lại hoặc hoàn ngân sách. Xem [luồng repair và mẫu gói](BOUNDED-REPAIR.md).
+
+Với task quá lớn cho một lượt, dùng `task slice-preview`, `task slice-plan` và
+`task slice-status` để chia thành các phần có mục tiêu, tệp và phụ thuộc rõ ràng
+trong cùng task. Phần cuối tích hợp toàn bộ điều kiện gốc trước review độc lập.
+Các phần dùng chung ngân sách hiện có; lịch sử, lượt thất bại và các cổng nghiệm
+thu vẫn được giữ. Xem [hướng dẫn chia nhỏ task](TASK-SLICING.md).