v0.11.1

Fixed

• ADR-002 restored. attune-author is no longer a required dependency
  of attune-help — moved back to the [authoring] optional extra. The
  0.11.0 release note that declared attune-author>=0.7.0 as a new
  required dep was a regression against ADR-002 ("zero required deps
  beyond python-frontmatter"); this release reverses it. Users who
  consume the deprecated attune_help.manifest / staleness /
  freshness shims now get a clear ImportError pointing them at
  pip install attune-help[authoring] instead of a transitive install.

Added

• 44 new tests across 5 new files (309 passing total): zero-dep
  install smoke test (real venv, @pytest.mark.slow), reusable
  StorageProtocolTester mixin, direct _find_template_file /
  _parse_template_file / cache tests (incl. CWE-22 path-traversal
  guard), AttuneHelpAdapter protocol-conformance tests, and direct
  unit tests for _require_str + the MCP engine/server factories.
• Branch-coverage gate at 81% (currently 82.31%), enforced via
  pyproject.toml's [tool.coverage.*] + a coverage cell on the
  ubuntu-latest × py3.11 matrix entry in CI. Coverage report
  uploaded as an artifact.
• New test-no-authoring-extra CI job that verifies the
  pytest.importorskip("attune_author") skip path actually works
  when the optional extra isn't installed.
• live pytest marker registered (deselected by default via
  addopts = "-ra -m 'not live'"). attune-help makes no LLM calls
  today; the marker is reserved so future tests have a consistent home.
• CI guard against ANTHROPIC_API_KEY in the default test env —
  fails fast as a regression alarm in both the matrix job and the
  test-no-authoring-extra job.

Changed

• tests/README.md replaces its inline LLM-mocking section with a
  pointer to the workspace-level testing-conventions.md (umbrella
  spec). Single source of truth across the attune-* family.

Dependencies

• Correction: the 0.11.0 entry incorrectly declared
  attune-author>=0.7.0 as a new required dependency. It was always
  intended to be the [authoring] extra; 0.11.0 shipped with it
  required by mistake, and 0.11.1 restores the intended shape. No
  action needed for users who installed attune-help[authoring];
  users who installed bare attune-help and hit shim ImportErrors
  should add the [authoring] extra explicitly.

v0.11.0 — deprecate attune_help.{manifest,staleness,freshness}; add rag adapter

Highlights

Phase B2 of the architecture-realignment spec. Closes finding #1 (ADR-002 violation: authoring code in attune-help) of the 2026-05-07 deep code review.

Changed (deprecation)

• attune_help.manifest, attune_help.staleness, attune_help.freshness (and attune_help.freshness.symbols) are now thin re-export shims around their new homes in attune_author.*. Each shim emits DeprecationWarning on import. Update your imports:

  # before
  from attune_help.manifest import Feature, FeatureManifest
  
  # after
  from attune_author.manifest import Feature, FeatureManifest

  The shims are scheduled for removal in the next minor release of attune-help (target: 2026-07-07).

• The package no longer eagerly re-exports manifest/staleness symbols from its top-level. A plain import attune_help is warning-free during the deprecation window.

Added

• attune_help.adapters.rag.AttuneHelpAdapter — frozen dataclass implementing attune_rag.corpus.help_adapter.HelpCorpusAdapter. Lets attune-rag build the help corpus with no dynamic import of attune-help.

Dependencies

• New required: attune-author>=0.7.0. Transitional — required only while the deprecation shims live; removed together with the shims on 2026-07-07. (Tech.md's "zero required deps" constraint is paused for the deprecation window.)

Architecture-realignment progress

Phases A (attune-rag #10), B1 (attune-author #14, packaged in v0.7.0), and B2 (this release) done. Phase C next: orchestration scaffold in attune-author.

Diff stat

+300 / −1090 — three internal modules (~1063 lines) collapse to four ~30-line shims plus the rag adapter.

v0.10.2

Update README: document template aliases frontmatter.

v0.10.1 — re-publish aliases (PyPI 0.10.0 was preempted)

What this release contains

Same change as the v0.10.0 release notes (5 templates gained alias frontmatter to close stemmer-induced retrieval gaps), but under a new version number because PyPI's 0.10.0 was preempted by an unrelated upload that did not contain the alias content.

Why a hot-fix

PyPI received an attune-help 0.10.0 upload on 2026-04-30 22:10 UTC that omitted the alias frontmatter shipped in #4. PyPI does not allow re-uploading the same version, so 0.10.1 is the next available number for the actual alias work to reach package consumers.

The 0.10.0 release on PyPI is being yanked separately so new installs resolve to 0.10.1.

Consumer pin compatibility

Existing pins continue to resolve cleanly:

• attune-rag[attune-help] → attune-help>=0.10.0,<0.11 ✓
• attune-author → attune-help>=0.10.0 ✓

v0.10.0 — template aliases to close stemmer-induced retrieval gaps

Highlights

Adds aliases: frontmatter to 5 templates so attune-rag's KeywordRetriever can match natural-language phrasings the Snowball stemmer drops on the floor. No code changes — pure template metadata.

Why

The Snowball stemmer maps planning → plann and never strips -ness, which left attune-rag's keyword retriever unable to match queries like "plan a feature" against tool-planning.md or "staleness" against tool-doc-audit.md. The retriever already weights template aliases at 1.5×, so adding targeted aliases is the documented mechanism for closing these gaps without changing the retriever or stemmer.

Templates updated

• concepts/tool-planning.md
• concepts/tool-bug-predict.md
• concepts/tool-fix-test.md
• references/tool-deep-review.md
• references/tool-doc-audit.md

Result

9 previously-failing golden retrieval tests in attune-rag now pass. attune-help own suite remains green at 246 tests; all 12 CI matrix combinations pass.

Pull request

#4 — #4

v0.9.0 — manifest/staleness + multi-doc + _docs bucket

Supersedes the unreleased 0.8.0 draft. Combines manifest + staleness
extraction from that draft with multi-doc support and a top-level
narrative-docs bucket.

Highlights

• Feature.doc_paths: list[str] — a feature may now register multiple docs.
• FeatureManifest.docs: list[str] — top-level _docs: bucket for
  hand-written narrative docs that don't belong to any single feature.
• check_staleness iterates doc_paths, producing one DocStaleness
  entry per registered path.
• Backward compatible: legacy doc_path: (scalar) loads cleanly, migrated
  into a single-entry list.

See CHANGELOG.md for full notes.

attune-help 0.7.0 — RAG-ready

Path-keyed summary sidecar + per-feature query fixtures + LLM polish pipeline. Makes attune-help the first retrieval-quality-tuned corpus in the ecosystem.

Retrieval benchmark (650 queries across 26 features)

Metric	Before (0.5.1)	After (0.7.0)
Precision@1	~0% effective	71.7%
Recall@3	~0% effective	81.5%

Clears the 70% P@1 gate from attune-ai's embeddings decision doc, deferring the fastembed v0.2.0 track.

What changed

• templates/summaries_by_path.json — 124 polished path-keyed summaries (replaces silently-ignored feature-keyed schema for RAG consumers).
• templates/fixtures/*.yaml — 26 per-feature query fixtures for regression benchmarks.
• Rolled forward 0.6.0's user-facing CLI (attune-help lookup, list, search, simpler).
• Development status: Beta (was Alpha).

Consumer action required

• attune-ai + attune-author: bump attune-help>=0.5.1,<0.6 to <0.8.
• attune-rag 0.1.2: point DirectoryCorpus at summaries_by_path.json.

Known quality variance: 6 features below 60% P@1 (documented in CHANGELOG), scheduled for 0.7.1.

v0.5.1

Deep-review fixes: bug fix, refactoring, and test coverage improvements.

Fixed

• [BLOCKING] lookup_simpler MCP handler created a fresh LocalFileStorage() to read depth back instead of using the engine's own storage instance — broke custom storage backends.
• list_topics parameter renamed from type to type_filter to avoid shadowing the Python builtin.
• precursor_warnings extension/filename maps extracted to module-level constants, reducing the method from 110 to ~10 lines.
• Category-name map consolidated: handlers now import _PREFIX_MAP from templates.py instead of re-declaring it.
• Repeated string-validation boilerplate across all 10 MCP handlers extracted into a shared _require_str() helper.
• _auto_detect_renderer return typed as Callable[[PopulatedTemplate], str] instead of Any.

Tests

• 20 new tests: renderer branches (error/warning/tip, marketplace, CLI plain), engine.get() coverage, and MCP handler error-path coverage.
• Overall coverage: 78% → 84%.

---

PyPI: https://pypi.org/project/attune-help/0.5.1/

v0.5.0

MCP layer catches up to the 0.4 HelpEngine public API. Everything added to the Python API in 0.4 is now reachable from an MCP client.

Added

• lookup_simpler MCP tool — step a topic one depth level back down, mirroring HelpEngine.simpler().
• lookup_list_topics MCP tool — flat slug enumeration optionally filtered by type (concepts, tasks, references, …).
• lookup_search MCP tool — fuzzy slug search returning ranked {slug, score} hits.
• lookup_suggest MCP tool — "did you mean" slug suggestions.
• lookup_reset now accepts an optional topic parameter to clear a single topic instead of the full session.
• lookup_status now returns the full per-topic depth map (topics) and LRU order (order) alongside the legacy last_topic / depth_level fields.
• "json" is now an accepted renderer across every MCP tool that renders content.
• Public attune_help.engine.VALID_RENDERERS constant so downstream code can derive allowlists from the same source the engine uses.

Fixed

• Renderer allowlist drift between HelpEngine and the MCP layer. The handler and schema enum now both derive from engine.VALID_RENDERERS, so adding a renderer automatically propagates to MCP.
• MCP lookup_reset previously wrote the legacy (pre-0.4) session schema, bypassing per-topic history. It now delegates to HelpEngine.reset().
• MCP tool count assertion was hardcoded — now uses the dispatch table as the source of truth.

Changed

• Nothing breaking. All existing MCP tool names and response shapes are preserved. New fields on lookup_status are additive; the topic parameter on lookup_reset is optional.

---

PyPI: https://pypi.org/project/attune-help/0.5.0/

v0.4.0

Added

• HelpEngine.list_topics(type=None, limit=None) — enumerate available topic slugs.
• HelpEngine.search(query, limit=10) — fuzzy slug search returning (slug, score) tuples.
• HelpEngine.suggest(topic, limit=5) — ranked suggestions for misspelled topics.
• HelpEngine.lookup(..., suggest_on_miss=True) — opt-in "did you mean" string when a lookup fails.
• HelpEngine.simpler(topic) — step one depth level back down without resetting session state.
• HelpEngine.reset(topic=None) — clear depth for one topic or the whole session.
• HelpEngine.set_renderer(name) — swap renderer at runtime.
• renderer="json" — deterministic structured output for apps, web dashboards, and snapshot tests.
• New attune_help.discovery module (topic index, search, suggest).
• precursor_warnings now recognizes JavaScript, TypeScript, JSX/TSX, Rust, Go, Ruby, and Java files.

Fixed

• HelpEngine.preamble() now resolves real bundled templates. Previously it only looked at the nested <feature>/task.md demo layout and silently returned None for the flat tasks/use-<feature>.md tree.
• Progressive depth no longer resets when users interleave topics. Per-topic depth history replaces the single-slot last_topic, bounded by an LRU cap of 32 topics.
• Depth-2 lookups now emit a terminal prompt ("reference — deepest level; say 'simpler' to step back") instead of nothing.
• render_claude_code no longer drops the body for concept, task, or unknown template types.
• HelpEngine.get_summary() falls back to the bundled summaries.json when an override directory doesn't ship one.
• auto renderer now respects sys.stdout.isatty() — piped output gets plain text, terminal output gets rich.

Changed

• Unknown renderer names now raise ValueError in HelpEngine.__init__ and set_renderer(). Previously they logged a warning and silently fell back to plain.
• Session schema gains topics and order fields for per-topic depth tracking. Legacy session files are read-migrated transparently — no action required for existing users.

---

PyPI: https://pypi.org/project/attune-help/0.4.0/