chore: prepare 0.27.9 release

[mohanagy]

Summary

• cut a stable 0.27.9 release branch from next so the accumulated next-track changes can land on main
• roll the README, changelog, and MCP registry metadata forward from 0.27.9-next.7 to stable 0.27.9
• switch the npm-facing README links from next to main for the stable release channel

Testing

• npm run release:verify
• npm run registry:validate
• npm run typecheck
• npm run build
• npm pack --dry-run
• npm sbom --sbom-format cyclonedx > /tmp/madar-0.27.9.sbom.cdx.json

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • MCP configuration now launches the installed madar command directly instead of version-pinned npx launchers, resolving Windows dependency issues.
  • Improved trace classification for tool discovery analytics.

• Documentation

  • Updated CLI help text for the install command to accept positional platform arguments (e.g., madar install claude).
  • Documentation updated to reflect stable v0.27.9 release.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 94079366-4bba-49f0-8794-77be52174a6b

📥 Commits

Reviewing files that changed from the base of the PR and between 01268c3 and 71011a1.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (12)

• CHANGELOG.md
• README.md
• docs/mcp-registry/server.json
• docs/reference/cli-and-mcp.md
• package.json
• src/cli/main.ts
• src/cli/parser.ts
• src/infrastructure/compare.ts
• src/infrastructure/install.ts
• tests/unit/cli.test.ts
• tests/unit/compare.test.ts
• tests/unit/install.test.ts

---

📝 Walkthrough

Walkthrough

This PR releases version 0.27.9 to stable, adds positional platform support to the madar install CLI command, refactors MCP server installation to use a bare madar command instead of version-pinned npx, extends Madar trace analysis with tool-discovery telemetry, and updates documentation branch references from "next" to "main".

Changes

v0.27.9 Release and Feature Updates

Layer / File(s)	Summary
Version bump and release documentation CHANGELOG.md, package.json, docs/mcp-registry/server.json, README.md, docs/reference/cli-and-mcp.md	Package version updated to 0.27.9 in package.json and registry metadata; changelog entries added for stable 0.27.9 and prerelease 0.27.9-next.7; README and documentation links switched from next branch to main across badges, tutorials, references, and telemetry links; MCP registry metadata clarified to document bare madar serve --stdio command instead of version-pinned npx launcher.
CLI install command positional platform support src/cli/main.ts, src/cli/parser.ts, tests/unit/cli.test.ts	Added exported INSTALL_USAGE constant for install command help text; updated parseInstallArgs to accept and validate positional platform arguments (e.g., madar install claude) alongside --platform flag, with validation using isInstallPlatform and rejection of duplicate/conflicting platform specifications; updated help text to show install [platform|--platform P] and example to madar install <platform>; extended test coverage for positional argument parsing and error cases.
MCP server installation using bare madar command src/infrastructure/install.ts, tests/unit/install.test.ts	Removed version-pinned npx-based MCP server command construction; refactored installMcpServer to build madar serve --stdio <graphPath> command using either directCliPath or fallback to PRIMARY_CLI_BIN_NAME; simplified function signature by removing nodePlatform parameter; updated all install call sites (installCopilotMcp, cursorInstall, claudeInstall) to pass only (projectDir, target, options); updated Claude and Cursor MCP server tests to assert bare madar command with serve --stdio args pointing to project-local graph file.
Madar trace tool-discovery telemetry and exploration classification src/infrastructure/compare.ts, tests/unit/compare.test.ts	Extended CompareMadarTraceTurnSummary with optional madar_tool_discovery_count and madar_tool_discovery_tool_indexes fields; added helper functions to detect deferred Madar tool-selection queries (isDeferredMadarToolSelectionQuery) and identify discovery tool calls (isMadarToolDiscoveryToolUse); updated exploration analysis loop to compute discovery tool index sets and conditionally skip discovery calls from affecting broad/focused exploration metrics; updated per-turn trace extraction to count and aggregate discovery telemetry across merged turns; added three comprehensive test cases covering ToolSearch behavior (deferred selection non-exploration, non-deferred selection as broad exploration, and mixed ordering within same turn).

Sequence Diagram

sequenceDiagram
  participant TurnAnalysis
  participant ToolCallIterator
  participant DiscoveryDetector
  participant ExplorationClassifier
  TurnAnalysis->>TurnAnalysis: compute discovery tool index set
  TurnAnalysis->>ToolCallIterator: iterate tool calls per turn
  ToolCallIterator->>DiscoveryDetector: check if toolsearch call is deferred Madar selection
  alt is discovery call
    DiscoveryDetector-->>ExplorationClassifier: skip from exploration metrics
  else is not discovery
    DiscoveryDetector-->>ExplorationClassifier: apply to broad/focused exploration
  end
  ExplorationClassifier->>ExplorationClassifier: classify outcome with discovery metadata

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The PR spans multiple distinct but related concerns: version bump and documentation updates (routine), CLI parser enhancement (moderate logic addition), MCP installation refactoring (moderate wiring change), and trace telemetry refinement (moderate complexity with new detection logic). Changes are heterogeneous across parser, installer, and analysis paths, requiring careful review of each layer's logic and test coverage.

Possibly related PRs

• mohanagy/madar#502: Core MCP server wiring change from version-pinned npx to bare madar serve --stdio command with corresponding install test updates.
• mohanagy/madar#504: Applies same CLI positional platform parsing and compare trace discovery tracking changes at code level.
• mohanagy/madar#321: Prior trace classification refinement work on Madar exploration outcome determination in compare.ts that laid foundation for tool-discovery tracking enhancement.

Poem

🐰 A stable release hops forward at last,
With madar commands running swift and fast—
No more npx versions pinned to the past,
And traces now find discovery at last! ✨

🚥 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 'chore: prepare 0.27.9 release' clearly and concisely summarizes the primary purpose of the PR: preparing and cutting a stable release.
Description check	✅ Passed	The PR description covers all required sections with substantive content: a clear Summary explaining the release preparation rationale, detailed Testing section with specific commands run, and implicit checklist compliance through the work performed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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 chore/release-0.27.9

---

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