@manhd_d/ai-harness 0.12.0 → 0.13.0

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)

package/docs/tool-setup/gemini-cli.md

@@ -1,41 +1,37 @@
 # Gemini CLI
 
-Install/authenticate from [official docs](https://geminicli.com/docs/), follow [common setup](README.md)
-and launch `gemini` at the initialized root.
+## Install and open
+
+1. Install/sign in using [official Gemini CLI docs](https://geminicli.com/docs/).
+2. Run [common setup](README.md) in your project root.
+3. In the existing root `GEMINI.md`, add the following line outside code fences. Create the file if
+   absent; preserve its other content:
 
-## Instructions and skills
-Gemini uses GEMINI.md by default. Merge an import into the existing root GEMINI.md if needed:
 ```markdown
 @./AGENTS.md
 ```
-Alternatively, merge `context.fileName` in the existing project settings.json so the list includes
-AGENTS.md while preserving other configured context names. Do not replace the entire settings file
-or use both routes to inflate context unnecessarily. `/memory show` checks loaded content and
-`/memory reload` refreshes it according to current official docs.
-Gemini documents .agents/skills as a workspace alias. Avoid duplicating the same skills in
-.gemini/skills; check current discovery and ask for the installed skill needed by the task.
-
-## 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)
-- [Context/imports/settings](https://geminicli.com/docs/cli/gemini-md/)
-- [Workspace skill aliases](https://geminicli.com/docs/cli/skills/)
-
-## Native model configuration
-Use [Agent preferences](../agent-configuration.md) with an explicitly available Google/Vertex model
-or reviewed mapping. Check the native /model picker against [official model selection](https://geminicli.com/docs/cli/model/).
-Main --model selection does not override native subagent models; configure them separately following
-[official subagents](https://geminicli.com/docs/core/subagents/) and your client's generation settings.
-Reasoning/thinking controls are model-specific. No OpenAI model is assumed to run directly here and
-no native JSON/agent file is created by aih. Verify actual delegation and capacity before parallel work.
+
+4. Run `gemini` from that project root.
+
+## Load and verify
+
+Gemini uses `GEMINI.md` by default. Inside its chat, run `/memory reload`, then `/memory show`
+to check imported instructions. It also discovers workspace `.agents/skills` as a native alias:
+use `/skills reload` and `/skills list` to inspect them.
+
+Run the [read-only setup prompt](README.md#3-check-loading-then-give-a-task).
+Do not duplicate skills into `.gemini/skills` or replace existing settings.
+
+## Optional configuration
+
+Instead of the import, an existing `context.fileName` setting can include `AGENTS.md`.
+Choose one route and preserve other context names.
+Model/provider choices remain native to Gemini; see [Agent configuration](../agent-configuration.md).
+Harness does not supply credentials or create native subagents.
+
+## Official references
+
+Checked 2026-10-13; no logged-in Gemini client or live-agent smoke was run.
+
+- [Context files, imports and memory checks](https://geminicli.com/docs/cli/gemini-md/)
+- [Skill aliases and loading checks](https://geminicli.com/docs/cli/skills/)

package/docs/tool-setup/kiro.md

@@ -0,0 +1,55 @@
+# Kiro
+
+## Install and open
+
+1. Install/sign in using [official Kiro installation](https://kiro.dev/docs/getting-started/installation/).
+   Choose the IDE or CLI for your environment.
+2. Run [common setup](README.md) in your project root.
+3. Open that folder in Kiro IDE and start a chat, or run `kiro-cli chat` from the same root.
+
+## Load and verify
+
+Kiro documents automatic root/nested `AGENTS.md` loading. Keep existing `.kiro/steering` files;
+you do not need to generate another full set of steering docs just to use Harness.
+
+Run the [read-only setup prompt](README.md#3-check-loading-then-give-a-task).
+Ask Kiro to read the needed `.agents/skills/<installed-name>/SKILL.md` explicitly.
+The official native skill path is `.kiro/skills`; this guide does not assume native discovery of
+Harness's `.agents/skills`.
+
+## Optional native skill pointer
+
+For slash invocation, create a project-owned file
+`.kiro/skills/harness-review/SKILL.md` without replacing existing files:
+
+```markdown
+---
+name: harness-review
+description: Review this project's changes against its installed Harness instructions.
+---
+Read AGENTS.md and .harness/local.md, then read and follow
+.agents/skills/harness-review/SKILL.md.
+Report findings, missing evidence and actual verification without changing files.
+```
+
+In Kiro IDE, inspect **Agent Steering & Skills** and the `/` skill menu.
+Verify the pointer actually loads the canonical skill in your session.
+Custom agents require explicit steering/skill resources; follow the official docs for your client.
+The pointer is yours to maintain; Harness does not generate, update or drift-check Kiro files.
+
+## Optional cloud/spec work
+
+For Kiro Web, commit the Harness files to its connected branch; verify workspace/tool access.
+Local steering, credentials and MCP connections are not automatically available in the cloud.
+When using Kiro Specs, declare which documents are canonical and their write scope in
+[Artifact contracts](../artifact-contract.md); do not silently create a competing source of truth.
+
+Models and permissions remain Kiro-controlled; see [Agent configuration](../agent-configuration.md).
+
+## Official references
+
+Checked 2026-10-13; no logged-in Kiro IDE/CLI/Web or live-agent smoke was run.
+
+- [CLI setup and commands](https://kiro.dev/docs/cli/setup/)
+- [Steering, AGENTS and custom-agent scope](https://kiro.dev/docs/steering/)
+- [Skills, native locations and resources](https://kiro.dev/docs/skills/)