Sync main into next

[mohanagy]

Summary

• merge the latest main branch into next to carry forward stable release changes
• keep the beta line aligned before starting the next issue branch

Verification

• npm run typecheck
• npm run build
• CI=1 npm run test:run

Summary by CodeRabbit

• Documentation

  • Streamlined README with Quickstart, updated examples, telemetry opt-in, and refreshed sections
  • Added docs: context packs overview and CLI/MCP reference
  • Updated CHANGELOG (0.27.8) and docs registry version

• Chores

  • Package version bumped to 0.27.8

• Tests

  • Updated unit tests and release-hygiene checks to validate new reference docs and release-branch link behavior

[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: 4f27b185-54b5-431a-a18c-66ed245cdedd

📥 Commits

Reviewing files that changed from the base of the PR and between 91faedc and 62abb89.

📒 Files selected for processing (3)

• README.md
• docs/reference/cli-and-mcp.md
• tests/unit/install-docs.test.ts

✅ Files skipped from review due to trivial changes (1)

• README.md

🚧 Files skipped from review as they are similar to previous changes (2)

• tests/unit/install-docs.test.ts
• docs/reference/cli-and-mcp.md

---

📝 Walkthrough

Walkthrough

Release v0.27.8: bump package/server versions, add CLI/MCP and context-pack docs, shorten README into a quickstart landing, enforce branch-correct README links in release-hygiene, and update tests to reference the new docs and aggregated public-docs corpus.

Changes

v0.27.8 Release with Documentation Restructuring

Layer / File(s)	Summary
Version and metadata update to 0.27.8 package.json, CHANGELOG.md, docs/mcp-registry/server.json	Version fields updated to 0.27.8; changelog adds the 0.27.8 entry documenting README/content relocation.
New reference and concept documentation docs/reference/cli-and-mcp.md, docs/concepts/context-packs.md, docs/...	Add CLI & MCP reference and context-pack concept docs: agent installs, strict/context-pack-first profiles, MCP registry metadata/validation, default tools, common commands, discovery rules, Pack Schema v1, and --spi guidance.
README refactor to npm-facing quickstart README.md	Condense README to a shorter landing with a Quickstart, rewritten product description, updated agent guidance, telemetry opt-in snippet, refreshed What’s New/--spi/Core Surfaces/Evidence/Trust sections, and updated docs table.
Release-hygiene: branch-aware README link validation .github/scripts/verify-release-hygiene.mjs	Introduce RELEASE_BRANCHED_README_PATHS and assertReleaseBranchedReadmeLinks to parse blob/<branch>/<path> URLs, compute expected branch from package version (- → next, otherwise main), and assert release-sensitive links target the correct branch; call-site updated in main().
Release-hygiene tests for branch targets tests/unit/release-hygiene.test.ts	Add tests asserting prereleases require blob/next and stable releases require blob/main for release-sensitive README doc links; verify verifier throws on mis-targeted fixtures.
Install documentation tests migrated to cli-and-mcp.md tests/unit/install-docs.test.ts	Migrate install-docs tests to docs/reference/cli-and-mcp.md; change table-style README assertions to toContain checks for CLI commands, lint/doctor surfaces, agent-specific paths, and refactor per-agent strict-profile assertions into loops.
MCP registry metadata tests migrated to cli-and-mcp.md tests/unit/mcp-registry-metadata.test.ts	Switch assertions for registry metadata path, npm run registry:validate, and trust-boundary wording to docs/reference/cli-and-mcp.md.
Why-madar honesty tests with expanded public corpus tests/unit/why-madar-doc.test.ts	Aggregate README plus new docs into publicDocs/publicLower; re-scope execution_slice, phase_coverage, MCP-surface, claim buckets, positioning, and Python-support assertions to run against combined corpus; validate claims pointer in docs/claims-and-evidence.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• mohanagy/madar#461: Also updates release-hygiene to compute expected blob branch from package version (main vs next).
• mohanagy/madar#466: Related README/docs refactor and test migrations to docs/reference/cli-and-mcp.md and related concept docs.
• mohanagy/madar#453: Overlaps on README/claims-and-evidence wording and expanded public-docs honesty test coverage.

🐰 A tidy bump, docs pruned and spry,

New reference trails to try,
Links that land on proper trees,
Quickstarts cached like winter peas,
Tests hop in — the release is nigh!

🚥 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 accurately reflects the PR's primary objective of merging main branch changes into the next branch for version alignment.
Description check	✅ Passed	The description covers the summary and verification steps, though it omits several template sections like testing checklist and the PR-focused checklist items.
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 sync-main-next-2026-06-02

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@docs/reference/cli-and-mcp.md`:
- Around line 50-64: The docs claim `context_pack` is full-profile-only, but
install guidance in src/infrastructure/install.ts (the strict compact MCP flow
that instructs agents to call `context_pack` once) contradicts that; update
docs/reference/cli-and-mcp.md to accurately reflect which profiles support
`context_pack`—either move `context_pack` from the "Full-profile additions" list
into the core/strict column or add a clarifying note that `--profile strict` (or
MADAR_TOOL_PROFILE=full/strict) enables a limited `context_pack` usage for the
strict flow, and ensure the README guidance for `--profile strict` explicitly
references the same behavior so `context_pack` availability is consistent with
src/infrastructure/install.ts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6944bfb7-fcda-47e3-8be4-52c6f06e97ca

📥 Commits

Reviewing files that changed from the base of the PR and between 0a3d9c3 and 91faedc.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (11)

• .github/scripts/verify-release-hygiene.mjs
• CHANGELOG.md
• README.md
• docs/concepts/context-packs.md
• docs/mcp-registry/server.json
• docs/reference/cli-and-mcp.md
• package.json
• tests/unit/install-docs.test.ts
• tests/unit/mcp-registry-metadata.test.ts
• tests/unit/release-hygiene.test.ts
• tests/unit/why-madar-doc.test.ts