mnem-suite 0.1.0__tar.gz

mnem_suite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Joakim Damsleth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mnem_suite-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mnem-suite
+Version: 0.1.0
+Summary: Meta-CLI and suite hub for the mnem memory suite (yaams, cognitive-ledger, owa-piggy, owa-tools)
+Author: Carl Joakim Damsleth
+License: MIT License
+        
+        Copyright (c) 2026 Carl Joakim Damsleth
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/damsleth/mnem
+Project-URL: Source, https://github.com/damsleth/mnem
+Keywords: mnem,memory,cli,agent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# mnem
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![status](https://img.shields.io/badge/status-pre--release-orange)
+
+**A local-first memory suite for AI agents.** One install gets you a
+two-tier memory store, an M365 read/write surface, and a single CLI
+that ties them together. Your data stays on your machine.
+
+`mnem` is the umbrella over four independent tools that already work
+on their own. The umbrella adds one verb surface, one install command,
+one place to find what is in the box.
+
+```
+                            mnem (meta-CLI + suite hub)
+                                       |
+              +------------------------+------------------------+
+              |               |                |                |
+            YAAMS    cognitive-ledger    owa-piggy        owa-tools
+         (Tier 1 raw)   (Tier 2 curated)  (M365 auth)   (M365 read/write)
+```
+
+## What's in the box
+
+| Tool | Purpose | Binaries |
+| --- | --- | --- |
+| [**YAAMS**](https://github.com/damsleth/yaams) | Tier 1 raw memory store - every iMessage, mail, calendar event, GitHub issue, ingested and queryable from a single SQLite file. | `yaams` |
+| [**cognitive-ledger**](https://github.com/damsleth/cognitive-ledger) | Tier 2 curated atomic notes engine - the gems you promote out of YAAMS and keep forever as markdown with frontmatter. | `ledger`, `ledger-obsidian`, `sheep` |
+| [**owa-piggy**](https://github.com/damsleth/owa-piggy) | Microsoft 365 auth broker - turns your existing Outlook Web session into a reusable token. No app registration. | `owa-piggy` |
+| [**owa-tools**](https://github.com/damsleth/owa-tools) | M365 read/write CLI suite - calendar, mail, Graph, OneDrive, scheduling, people lookup, all JSON-by-default. | `owa`, `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive` |
+
+`mnem` itself adds one more binary that routes the verbs above into
+a single user-facing surface.
+
+## Install
+
+```bash
+brew install damsleth/tap/mnem
+```
+
+The Homebrew formula pulls the whole suite via dependencies. On
+PyPI the package is `mnem-suite` (both `mnem` and `mnem-cli` were
+already taken on PyPI by unrelated projects); the installed binary
+is still `mnem`:
+
+```bash
+pipx install mnem-suite
+```
+
+Then:
+
+```bash
+mnem init           # detect sources, write config, run a dry-run
+mnem hello          # one-screen tour of the verbs
+mnem doctor         # health check across every tool
+```
+
+`mnem init` is idempotent and never edits your dotfiles.
+
+## What can it do
+
+```bash
+mnem query "what did we decide at the brand kickoff?"
+mnem ingest                       # all configured sources, partial-success tolerant
+mnem promote review               # interactive: promote YAAMS gems to the ledger
+mnem mail send --to ...           # owa-mail wrapper
+mnem calendar today               # owa-cal wrapper
+mnem ledger init                  # bootstrap a new ledger
+mnem auth status                  # owa-piggy wrapper
+mnem doctor                       # aggregate health check
+mnem version                      # own version + observed component versions
+```
+
+Every JSON-capable command accepts `--json` (machine mode) and
+`--pretty` (human rendering). Exit codes are predictable per
+[CONVENTIONS.md](CONVENTIONS.md): 0 ok, 1 user error, 2 transient,
+3 auth, 4 not found, 5 partial success.
+
+## First day
+
+1. `brew install damsleth/tap/mnem`
+2. `mnem init` - the wizard probes for iMessage, Apple Mail, Signal,
+   GitHub, owa-piggy, Obsidian, and an existing cognitive-ledger. It
+   enables what it finds and writes `enabled: false` with a hint for
+   what it doesn't.
+3. `mnem ingest` - first run downloads embedding models (~2 GB) with
+   a prompt before any download.
+4. `mnem query "..."` - ask the suite anything.
+
+See [SUITE.md](SUITE.md) for the full data flow and architecture, and
+[CONVENTIONS.md](CONVENTIONS.md) for the CLI contract every tool in
+the suite conforms to.
+
+## Skills
+
+Two agent skill repos sit on top of `mnem`:
+
+- [`damsleth/SKILLS`](https://github.com/damsleth/SKILLS) - public,
+  reusable agent skills. Includes `/memory`, which routes through
+  `mnem`.
+- `damsleth/SKILLS-private` - personal-infra `cj-*` skills (timereg,
+  did, weekly review). Same installer pattern; private repo.
+
+Skills wrap `mnem`. `mnem` does not call skills. One direction, no
+circular dependencies.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

mnem_suite-0.1.0/README.md

@@ -0,0 +1,109 @@
+# mnem
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![status](https://img.shields.io/badge/status-pre--release-orange)
+
+**A local-first memory suite for AI agents.** One install gets you a
+two-tier memory store, an M365 read/write surface, and a single CLI
+that ties them together. Your data stays on your machine.
+
+`mnem` is the umbrella over four independent tools that already work
+on their own. The umbrella adds one verb surface, one install command,
+one place to find what is in the box.
+
+```
+                            mnem (meta-CLI + suite hub)
+                                       |
+              +------------------------+------------------------+
+              |               |                |                |
+            YAAMS    cognitive-ledger    owa-piggy        owa-tools
+         (Tier 1 raw)   (Tier 2 curated)  (M365 auth)   (M365 read/write)
+```
+
+## What's in the box
+
+| Tool | Purpose | Binaries |
+| --- | --- | --- |
+| [**YAAMS**](https://github.com/damsleth/yaams) | Tier 1 raw memory store - every iMessage, mail, calendar event, GitHub issue, ingested and queryable from a single SQLite file. | `yaams` |
+| [**cognitive-ledger**](https://github.com/damsleth/cognitive-ledger) | Tier 2 curated atomic notes engine - the gems you promote out of YAAMS and keep forever as markdown with frontmatter. | `ledger`, `ledger-obsidian`, `sheep` |
+| [**owa-piggy**](https://github.com/damsleth/owa-piggy) | Microsoft 365 auth broker - turns your existing Outlook Web session into a reusable token. No app registration. | `owa-piggy` |
+| [**owa-tools**](https://github.com/damsleth/owa-tools) | M365 read/write CLI suite - calendar, mail, Graph, OneDrive, scheduling, people lookup, all JSON-by-default. | `owa`, `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive` |
+
+`mnem` itself adds one more binary that routes the verbs above into
+a single user-facing surface.
+
+## Install
+
+```bash
+brew install damsleth/tap/mnem
+```
+
+The Homebrew formula pulls the whole suite via dependencies. On
+PyPI the package is `mnem-suite` (both `mnem` and `mnem-cli` were
+already taken on PyPI by unrelated projects); the installed binary
+is still `mnem`:
+
+```bash
+pipx install mnem-suite
+```
+
+Then:
+
+```bash
+mnem init           # detect sources, write config, run a dry-run
+mnem hello          # one-screen tour of the verbs
+mnem doctor         # health check across every tool
+```
+
+`mnem init` is idempotent and never edits your dotfiles.
+
+## What can it do
+
+```bash
+mnem query "what did we decide at the brand kickoff?"
+mnem ingest                       # all configured sources, partial-success tolerant
+mnem promote review               # interactive: promote YAAMS gems to the ledger
+mnem mail send --to ...           # owa-mail wrapper
+mnem calendar today               # owa-cal wrapper
+mnem ledger init                  # bootstrap a new ledger
+mnem auth status                  # owa-piggy wrapper
+mnem doctor                       # aggregate health check
+mnem version                      # own version + observed component versions
+```
+
+Every JSON-capable command accepts `--json` (machine mode) and
+`--pretty` (human rendering). Exit codes are predictable per
+[CONVENTIONS.md](CONVENTIONS.md): 0 ok, 1 user error, 2 transient,
+3 auth, 4 not found, 5 partial success.
+
+## First day
+
+1. `brew install damsleth/tap/mnem`
+2. `mnem init` - the wizard probes for iMessage, Apple Mail, Signal,
+   GitHub, owa-piggy, Obsidian, and an existing cognitive-ledger. It
+   enables what it finds and writes `enabled: false` with a hint for
+   what it doesn't.
+3. `mnem ingest` - first run downloads embedding models (~2 GB) with
+   a prompt before any download.
+4. `mnem query "..."` - ask the suite anything.
+
+See [SUITE.md](SUITE.md) for the full data flow and architecture, and
+[CONVENTIONS.md](CONVENTIONS.md) for the CLI contract every tool in
+the suite conforms to.
+
+## Skills
+
+Two agent skill repos sit on top of `mnem`:
+
+- [`damsleth/SKILLS`](https://github.com/damsleth/SKILLS) - public,
+  reusable agent skills. Includes `/memory`, which routes through
+  `mnem`.
+- `damsleth/SKILLS-private` - personal-infra `cj-*` skills (timereg,
+  did, weekly review). Same installer pattern; private repo.
+
+Skills wrap `mnem`. `mnem` does not call skills. One direction, no
+circular dependencies.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

mnem_suite-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mnem-suite"
+version = "0.1.0"
+description = "Meta-CLI and suite hub for the mnem memory suite (yaams, cognitive-ledger, owa-piggy, owa-tools)"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "Carl Joakim Damsleth" }]
+keywords = ["mnem", "memory", "cli", "agent"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Development Status :: 4 - Beta",
+]
+dependencies = [
+  "click>=8.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/damsleth/mnem"
+Source = "https://github.com/damsleth/mnem"
+
+[project.scripts]
+mnem = "mnem.cli:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mnem*"]

mnem_suite-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mnem_suite-0.1.0/src/mnem/__init__.py

@@ -0,0 +1,3 @@
+"""mnem - meta-CLI for the mnem memory suite."""
+
+__version__ = "0.1.0"

mnem_suite-0.1.0/src/mnem/__main__.py

@@ -0,0 +1,4 @@
+from mnem.cli import main
+
+if __name__ == "__main__":
+  raise SystemExit(main())

mnem_suite-0.1.0/src/mnem/cli.py

@@ -0,0 +1,114 @@
+"""mnem Click root.
+
+Subcommands:
+- hello   - one-screen elevator pitch
+- version - mnem version + observed component versions
+- doctor  - aggregate health check across the suite
+- query   - passthrough to `yaams query` (with --tier aliasing)
+- ingest  - passthrough to `yaams ingest`
+- promote, ledger, mail, calendar, auth: Phase 3b
+
+Top-level flags: --version (Click default), --doctor, --json,
+--verbose. The doctor flag is wired so `mnem --doctor` works for
+parity with other binaries in the suite.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from mnem import __version__
+
+
+@click.group(
+  invoke_without_command=True,
+  context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(__version__, prog_name="mnem")
+@click.option(
+  "--doctor",
+  is_flag=True,
+  default=False,
+  help="Run health check across the suite and exit.",
+)
+@click.option(
+  "--json",
+  "as_json_top",
+  is_flag=True,
+  default=False,
+  help="Machine mode (JSON output) for top-level commands.",
+)
+@click.option(
+  "-v",
+  "--verbose",
+  is_flag=True,
+  default=False,
+  help="Verbose mode: dump captured stderr from subprocess failures.",
+)
+@click.pass_context
+def cli(ctx: click.Context, doctor: bool, as_json_top: bool, verbose: bool) -> None:
+  ctx.ensure_object(dict)
+  ctx.obj["json"] = as_json_top
+  ctx.obj["verbose"] = verbose
+  if doctor:
+    from mnem.commands.doctor import run as doctor_run
+    ctx.exit(doctor_run(as_json_top))
+  if ctx.invoked_subcommand is None:
+    from mnem.commands.hello import run as hello_run
+    ctx.exit(hello_run(as_json_top))
+
+
+@cli.command("hello")
+@click.option("--json", "as_json", is_flag=True, default=False)
+@click.pass_context
+def hello_cmd(ctx: click.Context, as_json: bool) -> None:
+  from mnem.commands.hello import run
+  ctx.exit(run(as_json or ctx.obj.get("json", False)))
+
+
+@cli.command("version")
+@click.option("--json", "as_json", is_flag=True, default=False)
+@click.pass_context
+def version_cmd(ctx: click.Context, as_json: bool) -> None:
+  from mnem.commands.version import run
+  ctx.exit(run(as_json or ctx.obj.get("json", False)))
+
+
+@cli.command("doctor")
+@click.option("--json", "as_json", is_flag=True, default=False)
+@click.pass_context
+def doctor_cmd(ctx: click.Context, as_json: bool) -> None:
+  from mnem.commands.doctor import run
+  ctx.exit(run(as_json or ctx.obj.get("json", False)))
+
+
+@cli.command(
+  "query",
+  context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def query_cmd(ctx: click.Context, args: tuple[str, ...]) -> None:
+  from mnem.commands.passthrough import run
+  ctx.exit(run(["query", *args], verbose=ctx.obj.get("verbose", False)))
+
+
+@cli.command(
+  "ingest",
+  context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def ingest_cmd(ctx: click.Context, args: tuple[str, ...]) -> None:
+  from mnem.commands.passthrough import run
+  ctx.exit(run(["ingest", *args], verbose=ctx.obj.get("verbose", False)))
+
+
+def main() -> int:
+  return cli(standalone_mode=False) or 0
+
+
+if __name__ == "__main__":
+  sys.exit(main())

mnem_suite-0.1.0/src/mnem/commands/__init__.py

@@ -0,0 +1 @@
+"""mnem subcommand implementations."""

mnem_suite-0.1.0/src/mnem/commands/doctor.py

@@ -0,0 +1,122 @@
+"""``mnem doctor`` - aggregate health check across the suite.
+
+Output class: data. Fans out to each `<tool> --doctor --json` and
+collects findings into one document.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TextIO
+
+from mnem import __version__
+from mnem.failure import run_subprocess
+
+
+# Order is the report order; mnem first, then tiers, then M365.
+_FANOUT = [
+  "yaams",
+  "ledger",
+  "sheep",
+  "ledger-obsidian",
+  "owa-piggy",
+  "owa-cal",
+  "owa-mail",
+  "owa-graph",
+  "owa-people",
+  "owa-sched",
+  "owa-drive",
+  "owa",
+]
+
+
+def _probe(binary: str) -> dict:
+  """Probe `<binary> --doctor --json` and return the parsed payload.
+
+  On crash or non-JSON output, synthesises a stub payload that
+  preserves the doctor-schema invariants (tool name, findings list).
+  """
+  result = run_subprocess([binary, "--doctor"], tool=binary, inject_json=True)
+  if result.crashed:
+    return {
+      "tool": binary,
+      "version": None,
+      "installed": False,
+      "findings": [
+        {
+          "id": "binary_missing",
+          "severity": "error",
+          "message": "binary not on PATH or crashed before emitting JSON",
+          "hint": f"brew install damsleth/tap/{binary} (or check PATH)",
+        }
+      ],
+    }
+  env = result.stdout_envelope or {}
+  env["installed"] = True
+  # Each binary's doctor exit code influenced findings already.
+  # Track the raw exit_code for the aggregator's severity rollup.
+  env["exit_code"] = result.returncode
+  return env
+
+
+def _aggregate() -> dict:
+  components = []
+  worst_exit = 0
+  for binary in _FANOUT:
+    payload = _probe(binary)
+    components.append(payload)
+    # Aggregate severity from two sources:
+    # (1) the subprocess returncode (clamped to the standard set), and
+    # (2) the findings list - an error-severity finding always bumps
+    # exit to at least 1, even if the binary itself returned 0.
+    sub_exit = int(payload.get("exit_code") or 0)
+    if not payload.get("installed", False):
+      # Missing binary -> user-fixable (install or PATH); not the raw
+      # FileNotFoundError exit (127).
+      sub_exit = 1
+    severities = {f.get("severity") for f in (payload.get("findings") or [])}
+    if "error" in severities:
+      sub_exit = max(sub_exit, 1)
+    worst_exit = max(worst_exit, sub_exit)
+  return {
+    "tool": "mnem",
+    "version": __version__,
+    "components": components,
+    "_exit_code": worst_exit,
+  }
+
+
+def run(as_json: bool, stream: TextIO | None = None) -> int:
+  if stream is None:
+    stream = sys.stdout
+  doc = _aggregate()
+  exit_code = int(doc.pop("_exit_code", 0))
+  if as_json:
+    stream.write(json.dumps(doc, ensure_ascii=False) + "\n")
+    stream.flush()
+    return exit_code
+
+  stream.write(f"mnem doctor (v{doc['version']})\n")
+  for comp in doc["components"]:
+    name = comp["tool"]
+    if not comp.get("installed"):
+      stream.write(f"  {name:<18}  - not installed\n")
+      continue
+    findings = comp.get("findings") or []
+    if not findings:
+      stream.write(f"  {name:<18}  ok\n")
+      continue
+    severities = {f["severity"] for f in findings}
+    if "error" in severities:
+      mark = "x"
+    elif "warning" in severities:
+      mark = "!"
+    else:
+      mark = "."
+    stream.write(f"  {name:<18}  {mark} {len(findings)} finding(s)\n")
+    for f in findings:
+      hint = f"  hint: {f['hint']}" if f.get("hint") else ""
+      stream.write(f"    - [{f['severity']}] {f['id']}: {f['message']}{hint}\n")
+  stream.flush()
+  return exit_code

mnem_suite-0.1.0/src/mnem/commands/hello.py

@@ -0,0 +1,67 @@
+"""``mnem hello`` - the one-screen elevator pitch.
+
+Output class: data. Runs without any config; safe on a fresh
+install before anything is wired up. Emits JSON on stdout under
+--json, a human banner otherwise.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TextIO
+
+from mnem import __version__
+from mnem.router import verbs
+
+
+# Static verbs that ship in 3a beyond the translation table.
+_BUILTIN_VERBS = [
+  ("hello", "mnem", "Show this elevator pitch"),
+  ("version", "mnem", "Show mnem version and observed component versions"),
+  ("doctor", "mnem", "Run health checks across the whole suite"),
+]
+
+
+def _all_verbs() -> list[tuple[str, str, str]]:
+  return _BUILTIN_VERBS + verbs()
+
+
+def _data_doc() -> dict:
+  return {
+    "tool": "mnem",
+    "version": __version__,
+    "tagline": "Local-first memory suite for AI agents.",
+    "verbs": [
+      {"verb": verb, "binary": binary, "description": desc}
+      for (verb, binary, desc) in _all_verbs()
+    ],
+    "next_steps": [
+      "mnem doctor",
+      "mnem query \"<question>\"",
+      "mnem ingest",
+    ],
+  }
+
+
+def run(as_json: bool, stream: TextIO | None = None) -> int:
+  if stream is None:
+    stream = sys.stdout
+  if as_json:
+    stream.write(json.dumps(_data_doc(), ensure_ascii=False) + "\n")
+    stream.flush()
+    return 0
+
+  doc = _data_doc()
+  stream.write(f"mnem v{doc['version']} - {doc['tagline']}\n\n")
+  stream.write("Verbs:\n")
+  width = max(len(v) for (v, _, _) in doc["verbs"] if isinstance(v, str)) if doc["verbs"] else 0
+  for entry in doc["verbs"]:
+    verb = entry["verb"]
+    desc = entry["description"]
+    stream.write(f"  {verb:<{width}}  {desc}\n")
+  stream.write("\nNext steps:\n")
+  for cmd in doc["next_steps"]:
+    stream.write(f"  $ {cmd}\n")
+  stream.flush()
+  return 0