attune-help

Lightweight help runtime with progressive depth and audience adaptation. Read project help templates generated by attune-ai.

Install

pip install attune-help

Quick Start

from attune_help import HelpEngine

engine = HelpEngine(template_dir=".help/templates")

# Progressive depth: concept -> task -> reference
print(engine.lookup("security-audit"))   # concept
print(engine.lookup("security-audit"))   # task
print(engine.lookup("security-audit"))   # reference

How It Works

Each topic has three depth levels:

Level	Type	What you get
0	Concept	What is it? When to use it?
1	Task	Step-by-step how-to
2	Reference	Full detail, edge cases

Repeated lookups on the same topic auto-advance. A new topic resets to concept.

Renderers

# Plain text (default)
engine = HelpEngine(renderer="plain")

# Rich terminal output (requires `pip install attune-help[rich]`)
engine = HelpEngine(renderer="cli")

# Claude Code inline format
engine = HelpEngine(renderer="claude_code")

# Auto-detect environment
engine = HelpEngine(renderer="auto")

Template Directory

Templates are markdown files with YAML frontmatter:

.help/templates/
  security/
    concept.md
    task.md
    reference.md
  api/
    concept.md
    task.md
    reference.md

Generate templates with attune-ai:

pip install attune-ai
# Then in Claude Code:
/coach init

Or create them manually — any markdown file with feature, depth, and source_hash frontmatter fields works.

Demo Templates

The package includes a demo feature showing the progressive depth format:

from attune_help import get_demo_path

# Copy to your project
import shutil
shutil.copytree(
    get_demo_path() / "security-audit",
    ".help/templates/security-audit",
)

The security-audit/ demo contains concept.md, task.md, and reference.md — the three depth levels that /coach init generates for each feature.

API

HelpEngine

HelpEngine(
    template_dir=None,    # Override template path
    storage=None,         # Session storage backend
    renderer="plain",     # Output renderer
    user_id="default",    # Session tracking ID
)

Methods:

• lookup(topic) — Progressive depth lookup
• get(template_id) — Direct template access
• lookup_raw(topic) — Returns PopulatedTemplate dataclass
• get_summary(skill) — One-line skill summary
• precursor_warnings(file_path) — File-aware warnings

SessionStorage Protocol

Implement custom storage backends:

from attune_help import SessionStorage

class RedisStorage(SessionStorage):
    def load(self, user_id: str) -> dict: ...
    def save(self, user_id: str, state: dict) -> None: ...

License

Apache 2.0