@manhd_d/ai-harness 0.12.0 → 0.14.0

package/docs/skill-matrix.md

@@ -1,6 +1,6 @@
-# Skill matrix — 70 skills, 13 nhóm module
+# Skill matrix — 66 skills, 15 nhóm module
 
-Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (6 Core, 42 capability, 22 adapter). Dùng khi cần chuyển từ [Full SDLC](end-to-end-workflow.md) tới một skill cụ thể, không nạp toàn bộ 70 skill vào prompt.
+Đây là bảng tra cứu **ID thật** theo `SKILL.md` trong source trên `main` (6 Core, 42 capability, 18 adapter). Dùng khi cần chuyển từ [Full SDLC](end-to-end-workflow.md) tới một skill cụ thể, không nạp toàn bộ 66 skill vào prompt.
 
 **Cách dùng:** `aih skills` xem skills đã cài, sau đó `aih skill harness-...` lấy nội dung. Danh mục này mô tả chức năng; **không** có nghĩa `aih` thực thi skills hoặc agent. Tech adapters và capabilities chỉ xuất hiện trong consumer khi được chọn; Core dùng chung.
 
@@ -84,8 +84,6 @@
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
-| [`harness-java-spring-database-migration`](../adapters/java-spring/skills/harness-java-spring-database-migration/SKILL.md) | DB change | Expand/migrate/contract theo release tương thích | Versioned migration và recovery evidence |
-| [`harness-java-spring-kafka-outbox`](../adapters/java-spring/skills/harness-java-spring-kafka-outbox/SKILL.md) | Async events | Outbox transaction và consumer dedupe | Event implementation + failure tests |
 | [`harness-java-spring-spring-api`](../adapters/java-spring/skills/harness-java-spring-spring-api/SKILL.md) | Backend API | Authorization resource scoped, API contract | Endpoint + auth/contract tests |
 
 ## React / Next.js adapter (4)
@@ -114,7 +112,7 @@
 | [`harness-ai-python-tool-safety`](../adapters/ai-python/skills/harness-ai-python-tool-safety/SKILL.md) | Agent tools | Bounded tools, explicit auth, no escalation | Policy wrapper + security tests |
 
 
-## Astro adapter (6)
+## Astro adapter (4)
 
 | Skill ID (nguồn) | Khi nào dùng | Mục đích | Output mong đợi |
 | --- | --- | --- | --- |
@@ -122,8 +120,6 @@
 | [`harness-astro-islands`](../adapters/astro/skills/harness-astro-islands/SKILL.md) | React Islands | Hydrate tương tác có chọn lọc, không nhầm Islands với MFE | Island component và UX tests |
 | [`harness-astro-seo`](../adapters/astro/skills/harness-astro-seo/SKILL.md) | SEO | Metadata, sitemap, nội dung hữu ích và a11y | Trang có metadata và kiểm chứng HTML |
 | [`harness-astro-performance`](../adapters/astro/skills/harness-astro-performance/SKILL.md) | Performance | JS budget, lazy loading, Web Vitals thực đo | Benchmark/build evidence |
-| [`harness-astro-cloudflare`](../adapters/astro/skills/harness-astro-cloudflare/SKILL.md) | Deploy | Static/CDN trước, Workers khi cần backend có kiểm soát | Kế hoạch Cloudflare và approval |
-| [`harness-astro-microfrontend`](../adapters/astro/skills/harness-astro-microfrontend/SKILL.md) | Scale | Lộ trình tách công cụ thành deploy riêng nếu thực cần | ADR/MFE migration checklist |
 
 ## Kubernetes adapter (3)
 
@@ -168,3 +164,7 @@ Product → Architecture → Delivery → Core/adapter uses [Solution workflow](
 ## Continuous development
 
 [Continuous development](continuous-development.md) composes existing Core spec/debugging/tdd/verification/review with Product business-analysis/acceptance-criteria/traceability/backlog/TechSpec, Architecture change-impact and Delivery scope-change skills. Only affected perspectives are loaded; no new role or skill is required.
+
+## Selective Product profiles
+
+Analysis exposes 11 and Discovery 5 canonical Product skills. IDs and source ownership stay Product; selecting both or the compatibility product bundle exposes each skill once. Profiles add module choices, not duplicate skill IDs. Canonical assets are vendored for valid shared references; this is selective context, not a smaller npm download.

package/docs/start.md

@@ -0,0 +1,38 @@
+# Bắt đầu một nhiệm vụ
+
+**init → start → làm việc trong AI tool.** Sau cài đặt, chạy trong project root:
+
+```bash
+npx --yes @manhd_d/ai-harness start
+```
+
+Terminal tương tác hỏi mục tiêu và task, input còn thiếu, nơi lưu draft docs khi cần.
+Có cấu hình input/output thì không hỏi lại. Có task đã lưu thì chọn tiếp tục hoặc nhiệm vụ mới;
+model/agent giữ mặc định của host trừ khi bạn muốn cấu hình khác. Lựa chọn được lưu trong
+`.harness/start.json` và `.harness/artifacts.json`; thay cấu hình hiện có tạo backup trước.
+
+Không có TTY (CI/pipe), `start` chỉ xuất JSON plan và không chờ stdin hoặc tự ghi lựa chọn.
+Có thể lưu lựa chọn bằng flags:
+
+```bash
+aih start --goal docs --task "Implement approved requirements" --input docs/requirements --output docs/specs
+aih start --goal change --task "Fix pagination"
+aih start --goal resume --task "Continue the reviewed task" --change add-order
+```
+
+Goal: `idea`, `docs`, `change`, `resume`. Resume cần checkpoint/evidence đã có, kiểm tra freshness và
+side effects trước tiếp tục. --input nhận đường dẫn tương đối hoặc HTTPS URL không chứa credentials;
+--output chỉ nhận folder docs tương đối. Flags input/output chỉ seed khi chưa có khai báo; muốn sửa
+nguồn cũ, review artifacts.json trực tiếp. Start không tự đọc tài liệu ngoài repo, không phê duyệt
+nghiệp vụ hay thực thi command/model. Metadata discovery không chứng minh nội dung nguồn đúng.
+
+Copy `host_prompt` từ kết quả vào AI tool đang mở cùng project. Host đọc task, cấu hình, nguồn và code;
+hỏi tối đa 1–3 quyết định còn thiếu mỗi lượt với phương án và đề xuất có lý do. Dùng workflow/agent/skill
+phù hợp đã cài; module thiếu phải được đề xuất rõ trước thay selection. Tiếp tục thực hiện khi scope và
+quyền đã đủ. Root-file probes không thay thế khảo sát monorepo hoặc đọc tài liệu trong host.
+
+Nếu bạn có nguồn/link/mô tả tự do hoặc cần output bên ngoài, đưa cho AI trong cuộc thảo luận và lưu
+quyết định vào artifacts.json/integrations.json/local.md. Terminal hỏi đáp ngắn; phần BA/thiết kế nằm
+trong AI tool. Không có slash command `/start` chung cho mọi tool ở bản này.
+
+[File cấu hình, backup, cài lại và chuyển dự án](configuration-backup.md) · [AI tool setup](tool-setup/README.md).

package/docs/tool-setup/README.md

@@ -1,75 +1,77 @@
-# Setup AI Harness with coding tools
+# Set up AI Harness in your AI tool
 
-Official discovery docs reviewed 2026-10-12. Authenticate/install the chosen host with its official
-instructions, then run Harness in the actual repository. Host/version/account capabilities vary;
-these are setup recipes, not a claim that native client behavior was tested in this workspace.
+Harness installs project instructions; it does not install an IDE, start an AI model or connect accounts.
+You need Node.js 22+, your chosen AI tool and a project folder.
+
+## 1. Install Harness in your project
+
+Open a terminal in the **project root** (the folder you open in your IDE), not in the ai-harness source repo:
 
-## Common setup
 ```bash
-npm install -g @manhd_d/ai-harness
-aih init --adapters java-spring --capabilities product,architecture,delivery
-aih check
-aih setup
-aih doctor
-aih skills
+npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness check
 ```
-Node.js 22+ is required by Harness; app stack remains independent. Replace adapter selection with
-react-nextjs/react-native/astro as appropriate. A coding-only maintain task can use just Core + adapter.
-For an existing install, edit .harness/project.json and reviewed update --dry-run/update/check.
 
-Fill .harness/local.md with mode, source docs/MVP/ADRs, public boundaries and actual commands; use
-[project configuration](../project-configuration.md) for Maven/JDK/settings and ignored machine paths.
-Do not bypass runtime permission policy or publish credentials. Configure GitHub/Figma/Confluence MCP
-only when needed, with the host's official setup and authorized access; Harness does not connect accounts.
+For a new app, create its repository/folder first. Core works with any stack.
+Use `init --detect` instead of `init` to select supported stacks, or choose optional adapters/capabilities
+in [Getting started](../getting-started.md). For an existing Harness installation, use the update steps below.
+
+`npx` does not install a global `aih` command. Optional: run
+`npm install -g @manhd_d/ai-harness`, then use `aih` instead of `npx --yes @manhd_d/ai-harness`.
+
+## 2. Open your AI tool
+
+Install/sign in through its official guide, open this same project and follow the matching Harness guide:
 
-| Host | Project entry | Skill handling | Guide |
+| AI tool | Install the tool | Load Harness | Guide |
 | --- | --- | --- | --- |
-| Codex CLI/IDE | AGENTS.md and applicable nested/override instructions | .agents/skills native discovery | [Codex](codex.md) |
-| Claude Code | Direct AGENTS support varies with current configuration/version; CLAUDE.md import fallback | .claude/skills wrapper when native slash invocation is desired; manual canonical read always possible | [Claude Code](claude-code.md) |
-| Cursor | AGENTS.md; existing .cursor/rules may also apply | .agents/skills discovery | [Cursor](cursor.md) |
-| Copilot | Client-specific AGENTS support or .github/copilot-instructions.md pointer | CLI supports .agents/skills; IDE support depends on client/version | [Copilot](copilot.md) |
-| Gemini CLI | GEMINI.md import or context.fileName includes AGENTS.md | .agents/skills workspace alias | [Gemini CLI](gemini-cli.md) |
-
-Preserve existing host files; merge only a reviewed pointer/import, never replace the whole config.
-Bridges are project-owned and not managed by aih. Keep one canonical skill body in .agents/skills;
-never copy every rule into each host config or advertise markdown role files as native agents.
-
-## Read-only setup smoke test
-Ask the host:
-```text
-Read the applicable AGENTS.md and .harness/local.md. Do not modify files or execute commands.
-State the selected adapters/capabilities and exact installed paths for solution-framing and one
-relevant skill. Summarize current project mode, known MVP/architecture decisions and missing facts.
-Explain which declarations the configured test command comes from; do not claim any test ran.
+| **Codex** | [CLI / IDE](https://developers.openai.com/codex/quickstart/) | `AGENTS.md`; native `.agents/skills` | [Setup](codex.md) |
+| **Claude Code** | [Install](https://code.claude.com/docs/en/setup) | `AGENTS.md` when enabled/not shadowed; otherwise a `CLAUDE.md` import | [Setup](claude-code.md) |
+| **Cursor** | [Install](https://cursor.com/docs) | `AGENTS.md`; native `.agents/skills` | [Setup](cursor.md) |
+| **GitHub Copilot** | [Install](https://docs.github.com/en/copilot) | Client-specific instructions; CLI native `.agents/skills` | [Setup](copilot.md) |
+| **Gemini CLI** | [Install](https://geminicli.com/docs/) | `GEMINI.md` import; native `.agents/skills` alias | [Setup](gemini-cli.md) |
+| **Kiro** | [IDE / CLI](https://kiro.dev/docs/getting-started/installation/) | `AGENTS.md`; read canonical skills explicitly or use optional native pointers | [Setup](kiro.md) |
+
+Existing instructions/settings remain yours. Do not replace host configs or copy the whole Harness into
+them. Host/version/account capabilities vary; these guides are not live-client compatibility results.
+
+## 3. Check loading, then give a task
+
+Send this **read-only prompt** in the AI chat:
+
+> Read AGENTS.md and .harness/local.md. Do not change files or run commands.
+> State the selected adapters/capabilities from .harness/project.json, the project's known decisions,
+> and one relevant installed skill with its exact path. Report anything you cannot read.
+
+Compare the answer with the actual files; a model's assertion alone does not prove loading.
+If skills are not discovered, ask it to read the needed `.agents/skills/<installed-name>/SKILL.md`.
+The tool guides show additional native loading checks. `check` verifies Harness files, not AI behavior.
+
+Then give your normal task:
+
+> Read AGENTS.md. Inspect the project and approved decisions. Implement [task], run appropriate
+> project tests and maintain affected specs/docs. Report actual results and anything blocked.
+
+You do not need to configure models, native subagents or MCP to begin. Harness role files are contracts,
+not automatically created native agents. See [Agent configuration](../agent-configuration.md) when needed.
+
+## Existing installs and updates
+
+Commit your current project state on a branch. Review and apply the new snapshot:
+
+```bash
+npx --yes @manhd_d/ai-harness@latest update --dry-run
+npx --yes @manhd_d/ai-harness@latest update
+npx --yes @manhd_d/ai-harness@latest check
 ```
-Expected: actual source paths, correct selection and no fabricated file/command/result. If automatic
-skill discovery fails, explicitly ask to read .agents/skills/<installed-name>/SKILL.md. `aih skills`
-is a catalog, and `aih skill <name>` prints canonical instructions; neither invokes an AI model.
-
-## Start prompts
-| Task | Prompt |
-| --- | --- |
-| Idea → MVP | Read Product product-to-solution; clarify the useful user journey, in/out scope and minimum quality before proposing architecture. |
-| Existing BA docs | Use the approved source/revision, extract only this change's requirements and gaps; preserve authoritative docs. |
-| SA design | Read Architecture discovery-to-design; compare minimal viable options, NFRs and justified feature patterns with actual decision sources. |
-| Maintain | Inspect touched module/code/tests and public common APIs; follow existing architecture and update only affected project-map entries. |
-| Delivery | Plan value slices/dependencies using real team estimates; unknown dates remain unknown; link AC/ADRs/OpenSpec. |
-
-## Update and troubleshoot
-Update the global CLI, then review snapshot update --dry-run/update/check. Restart/reload host discovery
-where required; read-only smoke again after setup changes. Keep custom host bridges and local.md.
-If a managed file conflicts, reconcile with Git rather than editing lock hashes. Check workspace root,
-nested override precedence, host context/trust settings, module selection and installed skill paths.
-Private VPN/tool access may be unavailable remotely; report blocked builds rather than inventing success.
-No logged-in host/MCP or live-agent smoke was run for these docs; follow each linked official guide.
-
-## Agent/model preferences
-
-Review [Agent configuration](../agent-configuration.md) and run `aih setup --host <id>` for a declared
-routing plan. Validate native model/effort in the actual picker/client; no account availability is
-probed or host config overwritten. Incompatible defaults need your explicit provider/model mapping.
-
-## Artifact destinations and connections
-After project setup, inspect artifacts.json/integrations.json and [Artifact contract](../artifact-contract.md).
-Resolve declared bindings against actual host tools; missing accounts/MCP/access remain unavailable.
-Reuse recorded storage and source-write scope, verify revisions and maintain docs/spec/UI with each change.
+
+Review the diff, run project tests and restart/reload your AI session if needed. With a global install,
+upgrade the CLI first. Keep project context in `.harness/local.md`; do not edit managed skills.
+
+For cloud work, the connected workspace must contain the installed project files and application tools;
+commit the snapshot to the working branch when the host obtains code from Git. Local-only files,
+credentials and MCP access are not automatically available remotely. Configure authorized connections
+through the host, then record source/output policies in [Artifact contracts](../artifact-contract.md).
+
+Official discovery references checked 2026-10-13; native login, cloud access and live-agent behavior
+were not tested here.

package/docs/tool-setup/claude-code.md

@@ -1,57 +1,49 @@
 # Claude Code
 
-Install/authenticate with [official setup](https://code.claude.com/docs/en/setup), then follow
-[common setup](README.md) and launch `claude` at the repository root.
+## Install and open
+
+1. Install/sign in using [official Claude Code setup](https://code.claude.com/docs/en/setup).
+2. Run [common setup](README.md) in your project root.
+3. Run `claude` from that same root.
+
+## Load and verify
+
+Direct `AGENTS.md` support requires Claude Code v2.1.277+ and the relevant instruction setting/plugin.
+By default, an existing `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the working directory
+or its ancestors can prevent direct loading.
+
+For a compatibility bridge, add this line outside code fences to the root `CLAUDE.md`; create it
+if absent and keep existing content:
 
-## Instructions
-Current Claude documentation describes direct AGENTS.md support with version/configuration conditions.
-If direct discovery is unavailable, add the following import to an existing project CLAUDE.md, or
-create the file if absent, without discarding any other content:
 ```markdown
 @AGENTS.md
 ```
-Check the host's loaded project instructions and nested/global files. Keep one canonical AGENTS;
-do not add a hook that prints a duplicate copy. The import remains a documented compatibility option.
+
+An import inside `.claude/CLAUDE.md` uses `@../AGENTS.md` instead.
+In Claude's chat, use `/context` to inspect loaded memory files, then run the
+[read-only setup prompt](README.md#3-check-loading-then-give-a-task).
+Organization policies may restrict loading; an import does not bypass them.
 
 ## Skills
-Claude documents .claude/skills for project skills. Harness does not assume .agents/skills is a native
-Claude skill location. Manual canonical loading from AGENTS instructions works without slash registration.
-If you want native invocation for a selected skill, create a small project-owned wrapper at
-.claude/skills/harness-product-mvp-definition/SKILL.md:
-```markdown
----
-name: harness-product-mvp-definition
-description: Define an MVP using this project's installed AI Harness instructions.
----
-Read the applicable AGENTS.md and then the canonical project file
-.agents/skills/harness-product-mvp-definition/SKILL.md. Follow its procedure and handoff;
-keep actual owner decisions and verification status explicit.
-```
-Then use `/harness-product-mvp-definition` in a supporting session. This wrapper is a pointer,
-not a copied skill body; maintain only needed wrappers and preserve existing native skills.
-
-## Verify and use
-Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
-known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
-ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
-all skill bodies. Application commands come from local.md/environment.json and actual build files.
-Follow host permission settings; no instruction creates missing account, network or tool access.
-
-## Update / troubleshooting
-Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
-review nested instructions and restart/reload the host when discovery changes. A Harness integrity
-check is separate from host discovery, app build or behavioral compliance. Native client login/setup
-was not exercised here; official references below establish the documented discovery mechanism.
-
-## Official references (checked 2026-10-12)
-- [Memory, AGENTS and imports](https://code.claude.com/docs/en/memory)
-- [Project skills and invocation](https://code.claude.com/docs/en/skills)
-
-## Native model configuration
-Use [Agent preferences](../agent-configuration.md) with an explicitly available Anthropic model or
-reviewed host mapping. OpenAI Sol/Astra preferences cannot run directly in Claude Code. Native model
-selection follows [official model config](https://code.claude.com/docs/en/model-config); use /model and
-client-supported effort controls, preserving existing settings/authentication. Native per-role agents
-use [official subagent format](https://code.claude.com/docs/en/sub-agents) in .claude/agents with model
-and supported effort settings. Role contracts can be referenced by a short instruction. aih does not
-write these files, infer account access or equate native Claude reasoning with OpenAI reasoning.
+
+Claude's native project skills live in `.claude/skills`, not Harness's `.agents/skills`.
+The basic setup works by asking Claude to read the needed canonical skill.
+For native slash invocation, use a small pointer wrapper rather than copying the skill body.
+
+The agent-first CLI adds opt-in `init/update --link-claude` for a managed import and
+`--claude-skills` for wrappers. These flags are unreleased from the 0.12.0 npm baseline:
+use them only with a reviewed source/new release that supports them. Without either flag,
+Harness does not edit Claude files. See [Agent-first guide](../agent-first.md).
+
+## Optional configuration
+
+Use [Agent configuration](../agent-configuration.md) only when needed; keep existing settings.
+Models, native agents and access remain Claude-controlled, not selected automatically by a role.
+
+## Official references
+
+Checked 2026-10-13; no logged-in Claude client or live-agent smoke was run.
+
+- [Memory, AGENTS conditions and imports](https://code.claude.com/docs/en/memory)
+- [Native skills](https://code.claude.com/docs/en/skills)
+- [Models](https://code.claude.com/docs/en/model-config)

package/docs/tool-setup/codex.md

@@ -1,44 +1,32 @@
-# Codex CLI and IDE
-
-Install/authenticate Codex from [official CLI](https://developers.openai.com/codex/cli/) or
-[IDE extension](https://developers.openai.com/codex/ide/), then follow [common setup](README.md).
-Launch `codex` or open the IDE at the initialized repository root.
-
-## Instructions and skills
-Codex reads AGENTS.md through its project hierarchy and can prefer AGENTS.override.md. Inspect
-applicable global/nested overrides when behavior differs; do not overwrite user defaults.
-Harness exposes declared skills in .agents/skills, the documented repository skill path. Start a new
-session after setup/update if needed; ask for one installed skill by name or canonical path.
-Markdown role contracts in .harness/core/agents and selected capabilities are read by the host;
-they are not automatically installed as native Codex subagents. .harness/local.md remains project context.
-
-## Verify and use
-Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
-known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
-ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
-all skill bodies. Application commands come from local.md/environment.json and actual build files.
-Follow host permission settings; no instruction creates missing account, network or tool access.
-
-## Update / troubleshooting
-Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
-review nested instructions and restart/reload the host when discovery changes. A Harness integrity
-check is separate from host discovery, app build or behavioral compliance. Native client login/setup
-was not exercised here; official references below establish the documented discovery mechanism.
-
-## Official references (checked 2026-10-12)
-- [AGENTS discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
-- [Skill discovery](https://learn.chatgpt.com/docs/build-skills)
+# Codex
+
+## Install and open
+
+1. Install/sign in using the [official quickstart](https://developers.openai.com/codex/quickstart/).
+2. Run [common setup](README.md) in your project root.
+3. Open that project in the Codex IDE extension, or run `codex` there.
+
+For a connected cloud workspace, commit the Harness snapshot to the branch used by the host.
+Cloud execution also needs the project's build tools and authorized repository access.
+
+## Load and verify
+
+Codex discovers root/applicable nested `AGENTS.md` and repository `.agents/skills`.
+An `AGENTS.override.md` can take precedence in the same directory; inspect it when instructions differ.
+Do not add a duplicate rule file or change global configuration just to start.
 
-## Native model configuration
-Follow [Agent preferences](../agent-configuration.md), then verify model access and supported effort.
-The official [config guide](https://learn.chatgpt.com/docs/config-file/config-basic) supports a reviewed
-merge into .codex/config.toml for CLI/IDE:
-```toml
-model = "gpt-6.1-sol"
-model_reasoning_effort = "medium"
-```
-For deliberate native agents use the current [subagent guide](https://learn.chatgpt.com/docs/agent-configuration/subagents).
-Standalone .codex/agents/*.toml uses name, description and developer_instructions, with optional model
-and model_reasoning_effort. Keep a small instruction pointing to the installed role/skill, not duplicated
-bodies. No files are generated/applied by aih; actual schema/client/account and thread-limit semantics
-must be checked. A normal session does not switch model automatically per Harness role.
+Start a new session after installation if needed. Run the [read-only setup prompt](README.md#3-check-loading-then-give-a-task)
+and compare its paths/selections with your files. Ask for the needed skill by name or exact path.
+
+## Optional configuration
+
+The host chooses models and actual subagents; Harness role files do not create native agents.
+See [Agent configuration](../agent-configuration.md) only when you need custom routing.
+Keep existing native settings and permissions; no model subscription or tool access is supplied by Harness.
+
+## Official references
+
+Checked 2026-10-13; no logged-in Codex client or live-agent smoke was run.
+
+- [AGENTS discovery and verification](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
+- [Skill discovery](https://learn.chatgpt.com/docs/build-skills)

package/docs/tool-setup/copilot.md

@@ -1,42 +1,39 @@
-# GitHub Copilot IDE and CLI
+# GitHub Copilot
 
-Install/sign in with [official Copilot docs](https://docs.github.com/en/copilot). In the IDE, open
-the project and use the supported Agent mode; for CLI start the authenticated `copilot` client at
-the root. Apply [common setup](README.md).
+## Install and open
+
+1. Install/sign in using [official Copilot docs](https://docs.github.com/en/copilot).
+2. Run [common setup](README.md) in your project root.
+3. Open the project in your IDE's supported Agent mode, or launch `copilot` from that root.
+
+## Load instructions
+
+Instruction support differs by client. VS Code documents `AGENTS.md`; do not assume every IDE behaves
+the same way. For a client needing a bridge, add this to the existing
+`.github/copilot-instructions.md` (create it if absent, preserving other instructions):
 
-## Instructions
-Support for AGENTS and skills varies between IDE/CLI/cloud features. Preserve existing settings.
-For a repository-wide IDE bridge, merge into .github/copilot-instructions.md:
 ```markdown
-Before implementation, read the applicable root/nested AGENTS.md and .harness/local.md.
-Follow the installed Core/selected capability workflows and only the relevant skill in .agents/skills.
-Report exact source paths, owner decisions and actual verification; do not infer test results.
+Read the applicable AGENTS.md and .harness/local.md before implementation.
+Use only the relevant installed skill from .agents/skills and report actual verification.
 ```
-This asks the agent to read files, not an automatic content import. Verify with the smoke prompt.
-Copilot CLI documents .agents/skills as a project skill directory; `/skills reload` and
-`/skills info <name>` can verify discovery there. IDE support must be checked for that specific client;
-use the canonical manual path when automatic discovery is unavailable.
-
-## Verify and use
-Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
-known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
-ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
-all skill bodies. Application commands come from local.md/environment.json and actual build files.
-Follow host permission settings; no instruction creates missing account, network or tool access.
-
-## Update / troubleshooting
-Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
-review nested instructions and restart/reload the host when discovery changes. A Harness integrity
-check is separate from host discovery, app build or behavioral compliance. Native client login/setup
-was not exercised here; official references below establish the documented discovery mechanism.
-
-## Official references (checked 2026-10-12)
-- [IDE repository instructions](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide)
-- [CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
-
-## Agent routing
-
-Read [Agent preferences](../agent-configuration.md). Verify current model picker/account and effort
-controls; aih setup --host copilot returns declarations only. Native per-role model switching or
-concurrency requires specific client support; otherwise perform roles sequentially with the selected
-session model. Never substitute premium or overwrite existing host settings automatically.
+
+This is a request to read files, not a content import. Run the
+[read-only setup prompt](README.md#3-check-loading-then-give-a-task) and compare with actual files.
+
+## Check skills
+
+Copilot CLI documents `.agents/skills`. Inside the CLI chat, run `/skills reload`, then
+`/skills info <installed-skill-name>`. IDE skill support depends on the actual client/version;
+when discovery is unavailable, ask the agent to read the canonical file explicitly.
+
+## Optional configuration
+
+Keep existing client settings. Model choice, native agents and permissions remain host-controlled;
+see [Agent configuration](../agent-configuration.md).
+
+## Official references
+
+Checked 2026-10-13; no logged-in Copilot client or live-agent smoke was run.
+
+- [Instructions by IDE](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide)
+- [CLI skill paths and loading checks](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)

package/docs/tool-setup/cursor.md

@@ -1,44 +1,29 @@
 # Cursor
 
-Install/sign in via [official Cursor docs](https://cursor.com/docs). Open the repository folder and
-Agent, then follow [common setup](README.md).
-
-## Instructions and skills
-Cursor supports project/nested AGENTS.md and .agents/skills. Preserve existing .cursor/rules and
-check their scope with project conventions before adding another rule. Ask Agent to read applicable
-AGENTS/local.md and use one installed skill; inspect discovery in the current client.
-If a specific workspace needs an explicit rule pointer, create a project-owned .cursor/rules/harness.mdc:
-```markdown
----
-description: Use the installed AI Harness for this repository.
-alwaysApply: true
----
-Read the applicable AGENTS.md and its referenced project context before changing code.
-Load only the installed skill needed for the task from .agents/skills.
-```
-Do not copy the full Harness snapshot into the rule. AGENTS already supplies the canonical entry;
-use this bridge only if needed, avoiding contradictory project/global/nested instructions.
-
-## Verify and use
-Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
-known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
-ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
-all skill bodies. Application commands come from local.md/environment.json and actual build files.
-Follow host permission settings; no instruction creates missing account, network or tool access.
-
-## Update / troubleshooting
-Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
-review nested instructions and restart/reload the host when discovery changes. A Harness integrity
-check is separate from host discovery, app build or behavioral compliance. Native client login/setup
-was not exercised here; official references below establish the documented discovery mechanism.
-
-## Official references (checked 2026-10-12)
-- [Rules and AGENTS](https://cursor.com/docs/rules)
-- [Skills and .agents discovery](https://cursor.com/docs/skills)
+## Install and open
+
+1. Install/sign in using [official Cursor docs](https://cursor.com/docs).
+2. Open your project folder in Cursor; use its integrated terminal for [common setup](README.md).
+3. Start an Agent chat in that same workspace.
+
+## Load and verify
+
+Cursor supports root/nested `AGENTS.md` and project `.agents/skills`; no extra rule is needed for normal setup.
+Preserve existing `.cursor/rules` and inspect their scope if instructions conflict.
+
+Open **Customize → Skills** to inspect discovered skills, then run the
+[read-only setup prompt](README.md#3-check-loading-then-give-a-task). If an installed skill is missing,
+reload the session or ask Agent to read its exact canonical file.
 
-## Agent routing
+## Optional configuration
 
-Read [Agent preferences](../agent-configuration.md). Verify current model picker/account and effort
-controls; aih setup --host cursor returns declarations only. Native per-role model switching or
-concurrency requires specific client support; otherwise perform roles sequentially with the selected
-session model. Never substitute premium or overwrite existing host settings automatically.
+Model/account choices and native delegation remain host-controlled; see [Agent configuration](../agent-configuration.md).
+For cloud work, commit the installed project files to the connected branch. Do not assume personal skills,
+local files or credentials are available remotely; see the official skill guide's cloud limitations.
+
+## Official references
+
+Checked 2026-10-13; no logged-in Cursor client or live-agent smoke was run.
+
+- [Rules and AGENTS](https://cursor.com/docs/rules)
+- [Skills, discovery and cloud scope](https://cursor.com/docs/skills)