docs: add install compatibility guide

[mohanagy]

Summary

• add a compatibility guide for dedicated install commands and madar install --platform surfaces
• link the guide from the README agent-install section and document generated files, verification paths, profile behavior, and limitations
• add install-compatibility regressions that cross-check the guide against actual installer output

Testing

• npm run typecheck
• npm run build
• CI=1 npm run test:run
• npm pack --dry-run

Closes #424

Summary by CodeRabbit

• Documentation

  • Updated README to direct users to new platform compatibility resources
  • Added comprehensive compatibility and installation guide documenting supported platform installers and cross-platform installation options, including generated artifacts, verification procedures, home-skill markers, platform aliasing behavior, and known limitations

• Tests

  • Added unit test coverage for installation compatibility contract

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds install compatibility documentation and comprehensive verification tests for supported agent platforms. A new user-facing compatibility guide documents the install matrix for both dedicated installers and --platform alias behavior, while a new test suite validates that the documentation matches actual installer outputs.

Changes

Install Compatibility Documentation and Verification

Layer / File(s)	Summary
Compatibility documentation README.md, docs/integrations/compatibility.md	README points readers to a new compatibility matrix covering dedicated install commands, generated files, verification steps, profile behavior, and platform-specific limitations for each supported agent platform.
Test types, data, and infrastructure tests/unit/install-compatibility.test.ts (lines 1–316)	Test-level types, large in-test datasets enumerating all supported platforms with their documented commands/artifacts/profiles, and utility functions for temp dir management, fixture package creation, and artifact assertions.
Artifact mapping and verification tests tests/unit/install-compatibility.test.ts (lines 318–462)	Platform-to-home-skill-artifact mapping function, tests verifying the compatibility guide documents all CLI platforms and includes expected artifact/constraint text, and artifact verification tests that execute installers and assert expected repo-local and home-skill file outputs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• mohanagy/madar#352: The new install-compatibility tests validate installer artifacts that are directly impacted by changes to hook-sentinel injection and hook-detection logic.
• mohanagy/madar#321: The compatibility documentation and tests validate install template outputs and profile behavior text that would be affected by installer guidance changes.

Poem

🐰 A guide to all the agents bright,
With files and paths all documented right,
Tests that catch when installs drift,
Users guided to the proper fix—a gift!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add install compatibility guide' is clear, concise, and directly describes the main change: adding a new documentation file for installation compatibility.
Description check	✅ Passed	The description covers the main changes (compatibility guide, README link, regression tests), includes comprehensive testing steps, and closes the related issue #424.
Linked Issues check	✅ Passed	The PR successfully addresses all acceptance criteria: documents expected generated files/config per agent, adds tests to catch install drift, and makes compatibility docs discoverable from README.
Out of Scope Changes check	✅ Passed	All changes (README update, compatibility guide, and install-compatibility tests) are directly scoped to issue #424's objectives of hardening agent install verification and documenting compatibility.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-424-install-compatibility

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/unit/install-compatibility.test.ts (1)

454-456: ⚡ Quick win

Also assert the .madar_version sibling marker.

The guide states every home-skill install writes SKILL.md plus a sibling .madar_version marker (and the verify text repeats it), but the artifact assertions only check SKILL.md. Asserting the marker too tightens drift detection per the PR's "detect changes in install templates" goal.

💚 Proposed marker assertion

-            installSkill(row.platform, { homeDir, packageRoot: bundledPackageRoot, version: 'test-version' })
-
-            expectArtifacts(homeDir, getHomeSkillArtifacts(row.platform))
+            installSkill(row.platform, { homeDir, packageRoot: bundledPackageRoot, version: 'test-version' })
+
+            const homeArtifacts = getHomeSkillArtifacts(row.platform)
+            expectArtifacts(homeDir, homeArtifacts)
+            for (const skill of homeArtifacts.filter((a) => a.endsWith('SKILL.md'))) {
+              expectArtifacts(homeDir, [skill.replace(/SKILL\.md$/, '.madar_version')])
+            }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/unit/install-compatibility.test.ts` around lines 454 - 456, The test
currently calls installSkill(...) and then expectArtifacts(homeDir,
getHomeSkillArtifacts(row.platform)) but only verifies SKILL.md; update the
assertions to also check for the sibling marker file `.madar_version` — either
by extending getHomeSkillArtifacts(row.platform) to include '.madar_version' or
by adding an explicit assertion after installSkill (e.g.,
expect(fs.existsSync(path.join(homeDir, '<skill-dir>',
'.madar_version'))).toBeTruthy()) so the test verifies both SKILL.md and the
`.madar_version` marker; modify the test near installSkill / expectArtifacts to
include the marker check.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/unit/install-compatibility.test.ts`:
- Around line 454-456: The test currently calls installSkill(...) and then
expectArtifacts(homeDir, getHomeSkillArtifacts(row.platform)) but only verifies
SKILL.md; update the assertions to also check for the sibling marker file
`.madar_version` — either by extending getHomeSkillArtifacts(row.platform) to
include '.madar_version' or by adding an explicit assertion after installSkill
(e.g., expect(fs.existsSync(path.join(homeDir, '<skill-dir>',
'.madar_version'))).toBeTruthy()) so the test verifies both SKILL.md and the
`.madar_version` marker; modify the test near installSkill / expectArtifacts to
include the marker check.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 16f8e95d-f874-4a33-8fc3-1e7b0afbb0ff

📥 Commits

Reviewing files that changed from the base of the PR and between 1278a6a and 8fea923.

📒 Files selected for processing (3)

• README.md
• docs/integrations/compatibility.md
• tests/unit/install-compatibility.test.ts