feat: add 'zday man' interactive documentation browser

- New zebra_day/cli/man.py with 12 topics, Rich markdown rendering,
  interactive menu, search, partial/numeric slug resolution,
  non-interactive fallback for piping
- Register man_app in cli/__init__.py
- Add docs/*.md to pyproject.toml package-data for pip distribution
- 15 new tests (304 total passing)

Author: iamh2o

pyproject.toml

@@ -94,6 +94,7 @@ include = ["zebra_day*"]
 [tool.setuptools.package-data]
 zebra_day = [
     "bin/*",
+    "docs/*.md",
     "etc/*",
     "etc/label_styles/*",
     "etc/label_styles/tmps/*",

tests/test_cli.py

@@ -253,3 +253,136 @@ def test_bootstrap_json_hides_scan_progress(self, mock_zpl_cls):
         assert result.exit_code == 0, result.output
         assert "Probing" not in result.output
         assert "printers_found" in result.output
+
+
+
+# ---------------------------------------------------------------------------
+# zday man — interactive documentation browser
+# ---------------------------------------------------------------------------
+
+
+class TestCLIManHelp:
+    """Tests for zday man --help output."""
+
+    def test_man_help(self):
+        """Test man --help shows expected options."""
+        result = runner.invoke(app, ["man", "--help"])
+        assert result.exit_code == 0
+        assert "Interactive documentation browser" in result.output
+        assert "--search" in result.output
+        assert "--list" in result.output
+
+    def test_man_in_main_help(self):
+        """man subcommand appears in top-level help."""
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        assert "man" in result.output
+
+
+class TestCLIManList:
+    """Tests for zday man --list."""
+
+    def test_list_topics(self):
+        """--list shows the topic table."""
+        result = runner.invoke(app, ["man", "--list"])
+        assert result.exit_code == 0
+        assert "Quickstart" in result.output
+        assert "CLI Reference" in result.output
+        assert "DynamoDB" in result.output
+        assert "Troubleshooting" in result.output
+
+
+class TestCLIManTopics:
+    """Tests for direct topic display."""
+
+    def test_quickstart(self):
+        """zday man quickstart renders content."""
+        result = runner.invoke(app, ["man", "quickstart"])
+        assert result.exit_code == 0
+        assert "Quickstart" in result.output
+
+    def test_cli_reference(self):
+        """zday man cli renders content."""
+        result = runner.invoke(app, ["man", "cli"])
+        assert result.exit_code == 0
+        assert "CLI Reference" in result.output
+
+    def test_gui(self):
+        """zday man gui renders the UI guide."""
+        result = runner.invoke(app, ["man", "gui"])
+        assert result.exit_code == 0
+        assert "GUI Usage" in result.output
+
+    def test_https(self):
+        """zday man https renders HTTPS docs."""
+        result = runner.invoke(app, ["man", "https"])
+        assert result.exit_code == 0
+        assert "HTTPS" in result.output
+
+    def test_hardware(self):
+        """zday man hardware renders hardware guide."""
+        result = runner.invoke(app, ["man", "hardware"])
+        assert result.exit_code == 0
+        assert "Hardware" in result.output
+
+    def test_unknown_topic_exits_1(self):
+        """Unknown topic prints error and exits 1."""
+        result = runner.invoke(app, ["man", "nonexistent_xyz"])
+        assert result.exit_code == 1
+        assert "Unknown topic" in result.output
+
+    def test_partial_match(self):
+        """Partial topic slug resolves correctly."""
+        result = runner.invoke(app, ["man", "quick"])
+        assert result.exit_code == 0
+        assert "Quickstart" in result.output
+
+    def test_numeric_topic(self):
+        """Numeric input resolves to topic by index."""
+        result = runner.invoke(app, ["man", "1"])
+        assert result.exit_code == 0
+        assert "Overview" in result.output
+
+
+class TestCLIManSearch:
+    """Tests for zday man --search."""
+
+    def test_search_finds_results(self):
+        """--search returns matching lines."""
+        result = runner.invoke(app, ["man", "--search", "printer"])
+        assert result.exit_code == 0
+        assert "matches" in result.output.lower() or "printer" in result.output.lower()
+
+    def test_search_no_results(self):
+        """--search with nonsense term shows no results."""
+        result = runner.invoke(app, ["man", "--search", "xyzzy_nonexistent_qwerty"])
+        assert result.exit_code == 0
+        assert "No results" in result.output
+
+
+class TestCLIManGracefulDegradation:
+    """Tests for graceful handling of missing doc files."""
+
+    def test_missing_file_shows_warning(self):
+        """A topic pointing to a missing file shows a warning, not a crash."""
+        from zebra_day.cli.man import TOPICS, Topic, TopicSource, _get_topic_content
+
+        fake_topic = Topic(
+            name="Missing",
+            description="test",
+            sources=[TopicSource("does_not_exist.md")],
+        )
+        content = _get_topic_content(fake_topic)
+        assert "not found" in content.lower()
+
+    def test_missing_section_shows_warning(self):
+        """A topic with a bad heading shows a warning, not a crash."""
+        from zebra_day.cli.man import TOPICS, Topic, TopicSource, _get_topic_content
+
+        fake_topic = Topic(
+            name="BadSection",
+            description="test",
+            sources=[TopicSource("README.md", "HEADING_THAT_DOES_NOT_EXIST_12345")],
+        )
+        content = _get_topic_content(fake_topic)
+        assert "not found" in content.lower()

zebra_day/cli/__init__.py

@@ -17,6 +17,7 @@
 from zebra_day.cli.dynamo import dynamo_app
 from zebra_day.cli.env import env_app
 from zebra_day.cli.gui import gui_app
+from zebra_day.cli.man import man_app
 from zebra_day.cli.printer import printer_app
 from zebra_day.cli.template import template_app
 
@@ -37,6 +38,7 @@
 app.add_typer(env_app, name="env", help="Development environment management")
 app.add_typer(cognito_app, name="cognito", help="Cognito authentication management")
 app.add_typer(dynamo_app, name="dynamo", help="DynamoDB shared configuration management")
+app.add_typer(man_app, name="man", help="Interactive documentation browser")
 
 
 def _get_version() -> str: