dotmd-parser 0.5.0__tar.gz → 0.7.0__tar.gz

{dotmd_parser-0.5.0 → dotmd_parser-0.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dotmd-parser
-Version: 0.5.0
-Summary: Dependency graph parser and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, and detect implicit dependencies via Claude for AI agent prompt engineering
+Version: 0.7.0
+Summary: Dependency graph parser, single-file folder index (dotmd-index.md), and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, generate RAG-friendly overviews, and ingest into OpenRAG
 Author: dotmd-projects
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/dotmd-projects/dotmd-parser
@@ -23,6 +23,16 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: openrag
+Requires-Dist: openrag-sdk>=0.3.1; extra == "openrag"
+Provides-Extra: pdf
+Requires-Dist: pdfplumber>=0.10; extra == "pdf"
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.0; extra == "docx"
+Provides-Extra: all
+Requires-Dist: openrag-sdk>=0.3.1; extra == "all"
+Requires-Dist: pdfplumber>=0.10; extra == "all"
+Requires-Dist: python-docx>=1.0; extra == "all"
 Dynamic: license-file
 
 # dotmd-parser
@@ -47,6 +57,35 @@ As AI agent projects grow, `.md` files start referencing each other via `@includ
 
 **dotmd-parser** solves this by parsing your `.md` files into a dependency graph — automatically detecting directives, runtime references, and template placeholders. One function call gives you the full picture.
 
+## Token savings — measured
+
+The single biggest reason to reach for `dotmd-parser` in an agent loop is
+that it lets Claude understand a folder **without reading every file**.
+The numbers below are produced by `tests/test_token_savings.py` (run
+with `DOTMD_TOKEN_REPORT=1 pytest -s`) using `tiktoken`'s `cl100k_base`
+encoding (a close proxy for Claude's tokenizer family):
+
+| Folder profile | Files | Naive read of every `.md` | `dotmd-index.md` | `digest` |
+|---|---:|---:|---:|---:|
+| Small skill (each file ~2 KB) | 4 | 1,610 tokens | **605 (0.38×)** | 174 (0.11×) |
+| Medium docs (each file ~2 KB) | 31 | 15,855 tokens | **2,837 (0.18× → 5.6× cheaper)** | 1,285 (0.08×) |
+| Large docs (each file ~2 KB) | 111 | 58,171 tokens | **9,535 (0.16× → 6.3× cheaper)** | 4,606 (0.08×) |
+
+**Takeaway**: at ~30 files dotmd-parser already cuts Claude's reading
+cost by **~5.6×**, and the savings *grow* with folder size. At 100+
+files the same context window now fits **6× more conversation**, or
+serves the same prompt at **1/6 the input-token spend**.
+
+The persistent `dotmd-index.md` artifact pays a fixed frontmatter
+overhead, so for *very small* folders (a handful of files of a few
+hundred bytes) the naive read can still win. The `digest` output is
+even more compact (~12× cheaper at scale) but isn't persisted on disk —
+use `dotmd-index.md` for stable navigation, `digest` for one-shot
+summaries.
+
+The break-even is around **4 files × 1 KB each**: above that,
+`dotmd-index.md` is always cheaper than reading the folder by hand.
+
 ## Comparison
 
 | Capability | Manual / grep | dotmd-parser |
@@ -177,6 +216,9 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 | Command | Purpose |
 |---|---|
 | `dotmd-parser inventory <path>` | **API-free**: extension counts, markdown/binary ratio, largest files |
+| `dotmd-parser dotmd-index <path>` | **API-free**: generate `<path>/dotmd-index.md` (single-file folder overview) |
+| `dotmd-parser dotmd-index <path> --aggregate` | Roll up nested `dotmd-index.md` files into the parent (Sub-Indexes section) |
+| `dotmd-parser dotmd-index <path> --push-openrag` | After writing, ingest into OpenRAG (`pip install dotmd-parser[openrag]`) |
 | `dotmd-parser index <path>` | Build and save `.claude/dotmd-index.json` |
 | `dotmd-parser index <path> --scope <subdir>` | Incrementally re-index one subfolder, merge into the existing index |
 | `dotmd-parser check <path>` | Exit non-zero on cycles / missing refs (CI-friendly) |
@@ -189,16 +231,80 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 | `dotmd-parser analyze <path> --dry-run` | **API-free**: estimate tokens and USD cost |
 | `dotmd-parser analyze <path> --plan` | **API-free**: emit a host-agent prompt pack for Claude Code to execute |
 | `dotmd-parser analyze <path> --apply-from <json>` | Apply a pre-computed analysis JSON |
+| `dotmd-parser init [--skill dotmd-index]` | Install a bundled SKILL.md into `.claude/skills/<id>/` |
 | `dotmd-parser show <path>` | Summary + full JSON graph (legacy default) |
 
 ```bash
 # Typical Claude Code workflow
-dotmd-parser inventory ./my-skill/       # start here if you've never seen the folder
-dotmd-parser index ./my-skill/           # one-off; cached until files change
-dotmd-parser digest ./my-skill/          # compact summary for the LLM
+dotmd-parser inventory ./my-skill/         # start here if you've never seen the folder
+dotmd-parser dotmd-index ./my-skill/       # write ./my-skill/dotmd-index.md (Claude reads ONLY this file)
+dotmd-parser index ./my-skill/             # one-off; cached until files change
+dotmd-parser digest ./my-skill/            # compact summary for the LLM
 dotmd-parser affects ./my-skill/ shared/role.md
 ```
 
+## `dotmd-index.md` — folder overview in a single file
+
+`dotmd-parser dotmd-index <path>` writes `<path>/dotmd-index.md`, a
+self-contained Markdown file that combines `inventory()` and
+`build_index()` into one artifact Claude can read **instead of**
+grep-scanning every file in the folder.
+
+The file contains:
+
+- YAML frontmatter (`schema`, `content_hash`, `stats`, RAG `chunks[]`)
+- `## Summary` (file counts, total size, health)
+- `## Folder Map` (depth-limited ASCII tree)
+- `## Files` (markdown: title + desc + deps; other: kind + size)
+- `## Dependency Tree` (`@include` / `@delegate` / `@ref` graph as ASCII)
+- `## Placeholders` (unresolved `{{...}}` variables)
+- `<!-- chunk:id -->` HTML markers so any RAG tool can split deterministically
+
+Re-running on an unchanged folder writes nothing (`content_hash` matches).
+The command refuses to overwrite a hand-written `dotmd-index.md` unless
+`--force` is passed.
+
+### Aggregating across nested folders
+
+Run with `--aggregate` to roll up descendant artifacts:
+
+```bash
+dotmd-parser dotmd-index ./project/ --aggregate
+# project/dotmd-index.md now references project/docs/dotmd-index.md and
+# project/src/dotmd-index.md without duplicating their file listings.
+```
+
+Each child is discovered, its frontmatter is read, and a one-line
+summary (file count, edges, health) appears under `## Sub-Indexes`.
+The `aggregates[]` frontmatter array records each child's `content_hash`
+so staleness is easy to detect. User-authored `dotmd-index.md` files
+that lack `generated_by: dotmd-parser` are silently skipped.
+
+This is a **reference**, not a merge — Claude reads the parent to learn
+which subfolders exist, then drills into the relevant child file. The
+parent stays token-efficient even with deeply nested trees.
+
+### OpenRAG integration
+
+[OpenRAG](https://github.com/langflow-ai/openrag) is a self-hosted RAG
+platform built on Langflow + Docling + OpenSearch. dotmd-parser can ship
+the artifact straight into it:
+
+```bash
+pip install dotmd-parser[openrag]       # adds openrag-sdk
+export OPENRAG_URL=http://localhost:3000
+export OPENRAG_API_KEY=...              # if your instance requires auth
+
+dotmd-parser dotmd-index ./docs/ --push-openrag
+# 1. Writes ./docs/dotmd-index.md
+# 2. Calls OpenRAGClient.documents.ingest(file_path=...)
+# 3. Records {document_id, base_url, pushed_at} in exports.openrag
+```
+
+`dotmd-index.md` is the **map** (one-shot overview); OpenRAG is the
+**search index** (full-content semantic retrieval). Register OpenRAG's
+MCP server with Claude Code to use both surfaces from the same client.
+
 ## `analyze` — AI-assisted dependency detection
 
 Use when a folder of markdown has **no explicit directives yet**. `analyze`

dotmd_parser-0.5.0/src/dotmd_parser.egg-info/PKG-INFO → dotmd_parser-0.7.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: dotmd-parser
-Version: 0.5.0
-Summary: Dependency graph parser and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, and detect implicit dependencies via Claude for AI agent prompt engineering
-Author: dotmd-projects
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/dotmd-projects/dotmd-parser
-Project-URL: Repository, https://github.com/dotmd-projects/dotmd-parser
-Project-URL: Issues, https://github.com/dotmd-projects/dotmd-parser/issues
-Keywords: claude-code,ai-agent,skill-management,prompt-engineering,dependency-graph,SKILL.md,markdown,parser,dotmd,llm
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Software Development :: Code Generators
-Classifier: Topic :: Text Processing :: Markup :: Markdown
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
 # dotmd-parser
 
 [![PyPI version](https://img.shields.io/pypi/v/dotmd-parser)](https://pypi.org/project/dotmd-parser/)
@@ -47,6 +20,35 @@ As AI agent projects grow, `.md` files start referencing each other via `@includ
 
 **dotmd-parser** solves this by parsing your `.md` files into a dependency graph — automatically detecting directives, runtime references, and template placeholders. One function call gives you the full picture.
 
+## Token savings — measured
+
+The single biggest reason to reach for `dotmd-parser` in an agent loop is
+that it lets Claude understand a folder **without reading every file**.
+The numbers below are produced by `tests/test_token_savings.py` (run
+with `DOTMD_TOKEN_REPORT=1 pytest -s`) using `tiktoken`'s `cl100k_base`
+encoding (a close proxy for Claude's tokenizer family):
+
+| Folder profile | Files | Naive read of every `.md` | `dotmd-index.md` | `digest` |
+|---|---:|---:|---:|---:|
+| Small skill (each file ~2 KB) | 4 | 1,610 tokens | **605 (0.38×)** | 174 (0.11×) |
+| Medium docs (each file ~2 KB) | 31 | 15,855 tokens | **2,837 (0.18× → 5.6× cheaper)** | 1,285 (0.08×) |
+| Large docs (each file ~2 KB) | 111 | 58,171 tokens | **9,535 (0.16× → 6.3× cheaper)** | 4,606 (0.08×) |
+
+**Takeaway**: at ~30 files dotmd-parser already cuts Claude's reading
+cost by **~5.6×**, and the savings *grow* with folder size. At 100+
+files the same context window now fits **6× more conversation**, or
+serves the same prompt at **1/6 the input-token spend**.
+
+The persistent `dotmd-index.md` artifact pays a fixed frontmatter
+overhead, so for *very small* folders (a handful of files of a few
+hundred bytes) the naive read can still win. The `digest` output is
+even more compact (~12× cheaper at scale) but isn't persisted on disk —
+use `dotmd-index.md` for stable navigation, `digest` for one-shot
+summaries.
+
+The break-even is around **4 files × 1 KB each**: above that,
+`dotmd-index.md` is always cheaper than reading the folder by hand.
+
 ## Comparison
 
 | Capability | Manual / grep | dotmd-parser |
@@ -177,6 +179,9 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 | Command | Purpose |
 |---|---|
 | `dotmd-parser inventory <path>` | **API-free**: extension counts, markdown/binary ratio, largest files |
+| `dotmd-parser dotmd-index <path>` | **API-free**: generate `<path>/dotmd-index.md` (single-file folder overview) |
+| `dotmd-parser dotmd-index <path> --aggregate` | Roll up nested `dotmd-index.md` files into the parent (Sub-Indexes section) |
+| `dotmd-parser dotmd-index <path> --push-openrag` | After writing, ingest into OpenRAG (`pip install dotmd-parser[openrag]`) |
 | `dotmd-parser index <path>` | Build and save `.claude/dotmd-index.json` |
 | `dotmd-parser index <path> --scope <subdir>` | Incrementally re-index one subfolder, merge into the existing index |
 | `dotmd-parser check <path>` | Exit non-zero on cycles / missing refs (CI-friendly) |
@@ -189,16 +194,80 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 | `dotmd-parser analyze <path> --dry-run` | **API-free**: estimate tokens and USD cost |
 | `dotmd-parser analyze <path> --plan` | **API-free**: emit a host-agent prompt pack for Claude Code to execute |
 | `dotmd-parser analyze <path> --apply-from <json>` | Apply a pre-computed analysis JSON |
+| `dotmd-parser init [--skill dotmd-index]` | Install a bundled SKILL.md into `.claude/skills/<id>/` |
 | `dotmd-parser show <path>` | Summary + full JSON graph (legacy default) |
 
 ```bash
 # Typical Claude Code workflow
-dotmd-parser inventory ./my-skill/       # start here if you've never seen the folder
-dotmd-parser index ./my-skill/           # one-off; cached until files change
-dotmd-parser digest ./my-skill/          # compact summary for the LLM
+dotmd-parser inventory ./my-skill/         # start here if you've never seen the folder
+dotmd-parser dotmd-index ./my-skill/       # write ./my-skill/dotmd-index.md (Claude reads ONLY this file)
+dotmd-parser index ./my-skill/             # one-off; cached until files change
+dotmd-parser digest ./my-skill/            # compact summary for the LLM
 dotmd-parser affects ./my-skill/ shared/role.md
 ```
 
+## `dotmd-index.md` — folder overview in a single file
+
+`dotmd-parser dotmd-index <path>` writes `<path>/dotmd-index.md`, a
+self-contained Markdown file that combines `inventory()` and
+`build_index()` into one artifact Claude can read **instead of**
+grep-scanning every file in the folder.
+
+The file contains:
+
+- YAML frontmatter (`schema`, `content_hash`, `stats`, RAG `chunks[]`)
+- `## Summary` (file counts, total size, health)
+- `## Folder Map` (depth-limited ASCII tree)
+- `## Files` (markdown: title + desc + deps; other: kind + size)
+- `## Dependency Tree` (`@include` / `@delegate` / `@ref` graph as ASCII)
+- `## Placeholders` (unresolved `{{...}}` variables)
+- `<!-- chunk:id -->` HTML markers so any RAG tool can split deterministically
+
+Re-running on an unchanged folder writes nothing (`content_hash` matches).
+The command refuses to overwrite a hand-written `dotmd-index.md` unless
+`--force` is passed.
+
+### Aggregating across nested folders
+
+Run with `--aggregate` to roll up descendant artifacts:
+
+```bash
+dotmd-parser dotmd-index ./project/ --aggregate
+# project/dotmd-index.md now references project/docs/dotmd-index.md and
+# project/src/dotmd-index.md without duplicating their file listings.
+```
+
+Each child is discovered, its frontmatter is read, and a one-line
+summary (file count, edges, health) appears under `## Sub-Indexes`.
+The `aggregates[]` frontmatter array records each child's `content_hash`
+so staleness is easy to detect. User-authored `dotmd-index.md` files
+that lack `generated_by: dotmd-parser` are silently skipped.
+
+This is a **reference**, not a merge — Claude reads the parent to learn
+which subfolders exist, then drills into the relevant child file. The
+parent stays token-efficient even with deeply nested trees.
+
+### OpenRAG integration
+
+[OpenRAG](https://github.com/langflow-ai/openrag) is a self-hosted RAG
+platform built on Langflow + Docling + OpenSearch. dotmd-parser can ship
+the artifact straight into it:
+
+```bash
+pip install dotmd-parser[openrag]       # adds openrag-sdk
+export OPENRAG_URL=http://localhost:3000
+export OPENRAG_API_KEY=...              # if your instance requires auth
+
+dotmd-parser dotmd-index ./docs/ --push-openrag
+# 1. Writes ./docs/dotmd-index.md
+# 2. Calls OpenRAGClient.documents.ingest(file_path=...)
+# 3. Records {document_id, base_url, pushed_at} in exports.openrag
+```
+
+`dotmd-index.md` is the **map** (one-shot overview); OpenRAG is the
+**search index** (full-content semantic retrieval). Register OpenRAG's
+MCP server with Claude Code to use both surfaces from the same client.
+
 ## `analyze` — AI-assisted dependency detection
 
 Use when a folder of markdown has **no explicit directives yet**. `analyze`

{dotmd_parser-0.5.0 → dotmd_parser-0.7.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "dotmd-parser"
-version = "0.5.0"
-description = "Dependency graph parser and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, and detect implicit dependencies via Claude for AI agent prompt engineering"
+version = "0.7.0"
+description = "Dependency graph parser, single-file folder index (dotmd-index.md), and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, generate RAG-friendly overviews, and ingest into OpenRAG"
 requires-python = ">=3.10"
 license = "MIT"
 readme = "README.md"
@@ -40,6 +40,16 @@ Homepage = "https://github.com/dotmd-projects/dotmd-parser"
 Repository = "https://github.com/dotmd-projects/dotmd-parser"
 Issues = "https://github.com/dotmd-projects/dotmd-parser/issues"
 
+[project.optional-dependencies]
+openrag = ["openrag-sdk>=0.3.1"]
+pdf = ["pdfplumber>=0.10"]
+docx = ["python-docx>=1.0"]
+all = [
+    "openrag-sdk>=0.3.1",
+    "pdfplumber>=0.10",
+    "python-docx>=1.0",
+]
+
 [project.scripts]
 dotmd-parser = "dotmd_parser.parser:main"
 
@@ -53,6 +63,7 @@ where = ["src"]
 [tool.setuptools.package-data]
 "dotmd_parser.templates" = ["*.md"]
 "dotmd_parser.templates.prompts" = ["*.md"]
+"dotmd_parser.templates.dotmd_index" = ["*.md"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{dotmd_parser-0.5.0 → dotmd_parser-0.7.0}/src/dotmd_parser/__init__.py

@@ -10,7 +10,7 @@ API:
     from dotmd_parser import digest, tree, affects
 """
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 from dotmd_parser.parser import (
     build_graph,
@@ -63,6 +63,14 @@ from dotmd_parser.inventory import (
     BINARY_EXTENSIONS,
     MARKDOWN_EXTENSIONS,
 )
+from dotmd_parser.index_md import (
+    generate_index_md,
+    write_index_md,
+    extract_frontmatter,
+    DEFAULT_INDEX_FILENAME,
+    INDEX_MD_SCHEMA,
+)
+from dotmd_parser.openrag import push_to_openrag
 
 __all__ = [
     "__version__",
@@ -112,4 +120,12 @@ __all__ = [
     "TEXT_EXTENSIONS",
     "BINARY_EXTENSIONS",
     "MARKDOWN_EXTENSIONS",
+    # index_md
+    "generate_index_md",
+    "write_index_md",
+    "extract_frontmatter",
+    "DEFAULT_INDEX_FILENAME",
+    "INDEX_MD_SCHEMA",
+    # openrag
+    "push_to_openrag",
 ]

{dotmd_parser-0.5.0 → dotmd_parser-0.7.0}/src/dotmd_parser/cli.py

@@ -53,6 +53,11 @@ from dotmd_parser.inventory import (
     format_inventory as _format_inventory,
     suggest_next_command as _suggest_next_command,
 )
+from dotmd_parser.index_md import (
+    DEFAULT_INDEX_FILENAME,
+    generate_index_md as _generate_index_md,
+    write_index_md as _write_index_md,
+)
 
 
 def _maybe_warn_empty(path: str) -> None:
@@ -88,20 +93,35 @@ def _load_or_build_index(path: str, use_cache: bool = True) -> dict:
 SKILL_DIR_NAME = "dotmd-parser"
 SKILL_TEMPLATE = "SKILL.md"
 
+# Map skill id (user-facing folder name) → package resource path
+_SKILLS = {
+    "dotmd-parser": ("dotmd_parser.templates", SKILL_TEMPLATE),
+    "dotmd-index": ("dotmd_parser.templates.dotmd_index", SKILL_TEMPLATE),
+}
+
 
-def _read_bundled_skill() -> str:
-    """Load the packaged SKILL.md via importlib.resources."""
-    return resources.files("dotmd_parser.templates").joinpath(SKILL_TEMPLATE).read_text(encoding="utf-8")
+def _read_bundled_skill(skill_id: str = "dotmd-parser") -> str:
+    """Load a packaged SKILL.md via importlib.resources."""
+    pkg, name = _SKILLS[skill_id]
+    return resources.files(pkg).joinpath(name).read_text(encoding="utf-8")
 
 
 def cmd_init(args: argparse.Namespace) -> int:
-    """Install the bundled SKILL.md into `<path>/.claude/skills/dotmd-parser/SKILL.md`."""
+    """Install a bundled SKILL.md into `<path>/.claude/skills/<skill-id>/SKILL.md`."""
     project = Path(args.path).resolve()
     if not project.exists():
         print(f"error: path does not exist: {project}", file=sys.stderr)
         return 2
 
-    target_dir = project / ".claude" / "skills" / SKILL_DIR_NAME
+    skill_id = args.skill or "dotmd-parser"
+    if skill_id not in _SKILLS:
+        print(
+            f"error: unknown skill {skill_id!r}; choose from {sorted(_SKILLS)}",
+            file=sys.stderr,
+        )
+        return 2
+
+    target_dir = project / ".claude" / "skills" / skill_id
     target = target_dir / SKILL_TEMPLATE
 
     if target.exists() and not args.force:
@@ -112,9 +132,12 @@ def cmd_init(args: argparse.Namespace) -> int:
         return 1
 
     target_dir.mkdir(parents=True, exist_ok=True)
-    target.write_text(_read_bundled_skill(), encoding="utf-8")
+    target.write_text(_read_bundled_skill(skill_id), encoding="utf-8")
     print(f"Installed skill: {target}")
-    print("Next: run `dotmd-parser index .` from the project root.")
+    if skill_id == "dotmd-parser":
+        print("Next: run `dotmd-parser index .` from the project root.")
+    elif skill_id == "dotmd-index":
+        print("Next: run `dotmd-parser dotmd-index .` to generate the artifact.")
     return 0
 
 
@@ -307,6 +330,73 @@ def cmd_inventory(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_dotmd_index(args: argparse.Namespace) -> int:
+    """Generate `<root>/dotmd-index.md` (or print to stdout). Optionally push to OpenRAG."""
+    gen_kwargs = {
+        "include_folder_map": not args.no_folder_map,
+        "include_deps_tree": not args.no_deps,
+        "max_files": args.max_files,
+        "aggregate": args.aggregate,
+    }
+
+    if args.stdout:
+        if args.push_openrag:
+            print("error: --stdout and --push-openrag are mutually exclusive", file=sys.stderr)
+            return 2
+        try:
+            md = _generate_index_md(args.path, **gen_kwargs)
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+        print(md, end="" if md.endswith("\n") else "\n")
+        return 0
+
+    try:
+        path, written = _write_index_md(args.path, force=args.force, **gen_kwargs)
+    except ValueError as e:
+        msg = str(e)
+        print(f"error: {msg}", file=sys.stderr)
+        if "does not exist" in msg or "is not a directory" in msg:
+            return 2
+        return 1
+    if written:
+        print(f"Wrote {path}")
+    else:
+        print(f"{path} unchanged (content_hash matches).")
+
+    if args.push_openrag:
+        from dotmd_parser.openrag import push_to_openrag as _push_to_openrag
+        try:
+            export = _push_to_openrag(
+                str(path),
+                base_url=args.openrag_url,
+                api_key=args.openrag_api_key,
+            )
+        except ImportError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 2
+        except (ValueError, RuntimeError) as e:
+            print(f"error: openrag push failed: {e}", file=sys.stderr)
+            return 1
+
+        # Re-emit the file with exports.openrag recorded — bypass idempotency
+        # check because we have explicit new metadata to persist.
+        md_with_export = _generate_index_md(
+            args.path,
+            extra_frontmatter={"exports": {"openrag": export}},
+            **gen_kwargs,
+        )
+        path.write_text(md_with_export, encoding="utf-8")
+        tid = export.get("task_id") or "<n/a>"
+        succ = export.get("successful_files", 0)
+        fail = export.get("failed_files", 0)
+        print(
+            f"Pushed to OpenRAG: {export.get('base_url')} "
+            f"(task_id={tid}, successful={succ}, failed={fail})"
+        )
+    return 0
+
+
 def cmd_show(args: argparse.Namespace) -> int:
     graph = build_graph(args.path)
     print(summary(graph))
@@ -325,8 +415,14 @@ def _build_parser() -> argparse.ArgumentParser:
 
     sub = parser.add_subparsers(dest="command")
 
-    p_init = sub.add_parser("init", help="Install bundled SKILL.md into .claude/skills/dotmd-parser/")
+    p_init = sub.add_parser("init", help="Install a bundled SKILL.md into .claude/skills/<id>/")
     p_init.add_argument("path", nargs="?", default=".", help="Project root (default: current directory)")
+    p_init.add_argument(
+        "--skill",
+        choices=sorted(_SKILLS),
+        default="dotmd-parser",
+        help="Which bundled skill to install (default: dotmd-parser)",
+    )
     p_init.add_argument("--force", action="store_true", help="Overwrite an existing SKILL.md")
     p_init.set_defaults(func=cmd_init)
 
@@ -404,6 +500,60 @@ def _build_parser() -> argparse.ArgumentParser:
     p_inv.add_argument("--json", action="store_true", help="Emit JSON instead of formatted text")
     p_inv.set_defaults(func=cmd_inventory)
 
+    p_idxmd = sub.add_parser(
+        "dotmd-index",
+        help=f"Generate {DEFAULT_INDEX_FILENAME} at <path>/ (single-file folder overview)",
+    )
+    p_idxmd.add_argument("path", help="Directory to summarize")
+    p_idxmd.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Print to stdout instead of writing to <path>/dotmd-index.md",
+    )
+    p_idxmd.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing file even if it isn't a dotmd-parser artifact",
+    )
+    p_idxmd.add_argument(
+        "--no-folder-map",
+        action="store_true",
+        help="Skip the ASCII folder-map section",
+    )
+    p_idxmd.add_argument(
+        "--no-deps",
+        action="store_true",
+        help="Skip the dependency-tree section",
+    )
+    p_idxmd.add_argument(
+        "--max-files",
+        type=int,
+        default=200,
+        help="Cap on the number of files listed in the body (default: 200)",
+    )
+    p_idxmd.add_argument(
+        "--aggregate",
+        action="store_true",
+        help="Discover descendant dotmd-index.md artifacts and reference them "
+             "(adds a ## Sub-Indexes section + aggregates[] frontmatter)",
+    )
+    p_idxmd.add_argument(
+        "--push-openrag",
+        action="store_true",
+        help="After writing, ingest the file into OpenRAG (requires `pip install dotmd-parser[openrag]`)",
+    )
+    p_idxmd.add_argument(
+        "--openrag-url",
+        metavar="URL",
+        help="OpenRAG endpoint (default: $OPENRAG_URL or http://localhost:3000)",
+    )
+    p_idxmd.add_argument(
+        "--openrag-api-key",
+        metavar="KEY",
+        help="OpenRAG API key (default: $OPENRAG_API_KEY, handled by the SDK)",
+    )
+    p_idxmd.set_defaults(func=cmd_dotmd_index)
+
     p_show = sub.add_parser("show", help="Legacy summary + full JSON graph")
     p_show.add_argument("path", help="Directory or SKILL.md")
     p_show.add_argument("--quiet", action="store_true", help="Suppress JSON dump")
@@ -417,7 +567,7 @@ def run(argv: list[str] | None = None) -> int:
     args_list = list(sys.argv[1:] if argv is None else argv)
 
     # Backwards compatibility: `dotmd-parser <path>` with no subcommand → show
-    known_cmds = {"init", "index", "check", "affects", "deps", "digest", "tree", "resolve", "analyze", "inventory", "show"}
+    known_cmds = {"init", "index", "check", "affects", "deps", "digest", "tree", "resolve", "analyze", "inventory", "dotmd-index", "show"}
     if args_list and args_list[0] not in known_cmds and not args_list[0].startswith("-"):
         args_list = ["show", *args_list]
     if not args_list: