feat: initial commit — attune-help extracted from attune-ai monorepo

Extracted from Smart-AI-Memory/attune-ai/packages/attune-help/ to give
this Python package its own dedicated repo, CI, and PyPI trusted-publishing
path.

Changes from the monorepo version:
- Version bump 0.3.0 → 0.3.1
- Drop plugin/ subdirectory (Claude Code plugin wrapper now lives in
  Smart-AI-Memory/attune-docs)
- Add .github/workflows/publish.yml for trusted-publishing to PyPI

Fixes the attune-help MCP server runtime startup (plugin .mcp.json uses
`uv run --from 'attune-help[plugin]'`) which was broken because the
published PyPI version 0.3.0 didn't have the [plugin] extra registered.
This repo ships 0.3.1 with the extra properly declared in pyproject.toml.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: silversurfer562

.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        # No token needed - uses OIDC trusted publishing

.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+.uv/

LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   Copyright 2026 Smart AI Memory
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,141 @@
+# attune-help
+
+Lightweight help runtime with progressive depth and
+audience adaptation. Read project help templates
+generated by [attune-ai](https://pypi.org/project/attune-ai/).
+
+## Install
+
+```bash
+pip install attune-help
+```
+
+## Quick Start
+
+```python
+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
+
+```python
+# 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](https://pypi.org/project/attune-ai/):
+
+```bash
+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:
+
+```python
+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`
+
+```python
+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:
+
+```python
+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

pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "attune-help"
+version = "0.3.1"
+description = "Lightweight help runtime with progressive depth and audience adaptation."
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Patrick Roebuck", email = "admin@smartaimemory.com"}
+]
+keywords = ["help", "documentation", "progressive-depth", "templates"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "python-frontmatter>=1.0.0",
+]
+
+[project.optional-dependencies]
+rich = ["rich>=13.0.0"]
+plugin = ["mcp>=0.9.0"]
+
+[project.scripts]
+attune-help-mcp = "attune_help.mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/Smart-AI-Memory/attune-ai"
+Repository = "https://github.com/Smart-AI-Memory/attune-ai"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+attune_help = ["templates/**/*.md", "templates/**/*.json", "demos/**/*.md"]

src/attune_help/__init__.py

@@ -0,0 +1,36 @@
+"""attune-help: Lightweight help runtime with progressive depth.
+
+Provides template loading, progressive depth escalation,
+audience adaptation, and feedback scoring — without the
+full attune-ai authoring toolkit.
+"""
+
+from __future__ import annotations
+
+from attune_help.demos import get_demo_path
+from attune_help.engine import (
+    AudienceProfile,
+    HelpEngine,
+    PopulatedTemplate,
+    TemplateContext,
+)
+from attune_help.preamble import get_preamble  # noqa: F401
+from attune_help.storage import LocalFileStorage, SessionStorage
+
+__all__ = [
+    "AudienceProfile",
+    "HelpEngine",
+    "LocalFileStorage",
+    "PopulatedTemplate",
+    "SessionStorage",
+    "TemplateContext",
+    "get_demo_path",
+    "get_preamble",
+]
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("attune-help")
+except Exception:  # noqa: BLE001
+    __version__ = "dev"

src/attune_help/demos/__init__.py

@@ -0,0 +1,13 @@
+"""Demo templates showing the per-feature help format.
+
+Contains a ``security-audit`` feature with concept, task,
+and reference templates.  Copy the feature directory into
+your project's ``.help/templates/`` as a starting point.
+"""
+
+from pathlib import Path
+
+
+def get_demo_path() -> Path:
+    """Return path to the bundled demo templates directory."""
+    return Path(__file__).resolve().parent

src/attune_help/demos/security-audit/concept.md

@@ -0,0 +1,44 @@
+---
+feature: security-audit
+depth: concept
+generated_at: "2026-04-05T00:00:00+00:00"
+source_hash: demo
+status: demo
+---
+
+# Security Audit
+
+A security audit scans your codebase for vulnerabilities
+that are easy to introduce and hard to spot in code
+review. It catches the mistakes that slip through when
+you're focused on making things work — an `eval()` in a
+test fixture, a file path built from user input without
+validation, an API key that ended up in source control.
+
+## What it finds
+
+| Category | What to worry about |
+|----------|---------------------|
+| **Code injection** | `eval()`, `exec()`, and `compile()` on untrusted input |
+| **Path traversal** | File operations that don't validate the path first |
+| **Hardcoded secrets** | API keys, tokens, and passwords committed to source |
+| **SQL/command injection** | String concatenation in queries or shell commands |
+| **SSRF** | HTTP requests to URLs controlled by user input |
+| **Weak cryptography** | MD5/SHA1 for security purposes, hardcoded IVs |
+
+## Why it matters
+
+These vulnerabilities are common in everyday code —
+they're not exotic attacks. A path traversal bug is just
+a missing validation call. A hardcoded secret is a
+string that should have been an environment variable.
+Automated scanning catches these before they reach
+production.
+
+## How deep it goes
+
+| Depth | Time | What you get |
+|-------|------|-------------|
+| **Quick** | ~30s | Surface scan — eval/exec, obvious secrets |
+| **Standard** | ~2 min | Full pattern matching with severity ratings |
+| **Deep** | ~5 min | Multi-pass review with OWASP mapping and fix suggestions |