Add built-in docs subcommand

Author: pasunboneleve

CHANGELOG.md

@@ -14,6 +14,9 @@ All notable changes to `devloop` will be recorded in this file.
   `devloop` without polling.
 - Added dedicated security documentation for external events and the
   push-versus-polling tradeoffs in [`docs/security.md`](docs/security.md).
+- Added `devloop docs <topic>` so the configuration, behavior, and
+  security references can be read directly from the CLI without
+  duplicating the source material.
 
 ### Changed
 - Moved workflow progression into a pure state/effect core so ordered

README.md

@@ -65,6 +65,14 @@ The tool will:
 * watch configured paths
 * execute workflows on change
 
+Built-in reference docs are also available from the CLI:
+
+```bash
+devloop docs config
+devloop docs behavior
+devloop docs security
+```
+
 ## Design
 
 The tool has three layers:

docs/behavior.md

@@ -3,6 +3,12 @@
 This document describes how `devloop` behaves at runtime beyond the
 schema in [`configuration.md`](configuration.md).
 
+This reference is also available in the CLI with:
+
+```bash
+devloop docs behavior
+```
+
 ## Core model
 
 `devloop` is moving toward a pure core with an imperative shell.

docs/configuration.md

@@ -3,6 +3,12 @@
 `devloop` is configured with a TOML file, typically `devloop.toml` in
 the client repository root.
 
+This reference is also available in the CLI with:
+
+```bash
+devloop docs config
+```
+
 ## Top-level keys
 
 ```toml

docs/security.md

@@ -3,6 +3,12 @@
 This document describes the trust model and security tradeoffs for
 `devloop` features that accept input from outside the core watch loop.
 
+This reference is also available in the CLI with:
+
+```bash
+devloop docs security
+```
+
 ## Threat model
 
 `devloop` supervises local processes, runs hooks, persists session

src/main.rs

@@ -9,7 +9,7 @@ mod state;
 use std::path::PathBuf;
 
 use anyhow::{Result, anyhow};
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueEnum};
 use tracing::{Event, Subscriber};
 use tracing_subscriber::EnvFilter;
 use tracing_subscriber::fmt::FmtContext;
@@ -47,6 +47,18 @@ enum Command {
         #[arg(long)]
         config: Option<PathBuf>,
     },
+    /// Print built-in reference documentation.
+    Docs {
+        #[arg(value_enum)]
+        topic: DocsTopic,
+    },
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+enum DocsTopic {
+    Config,
+    Behavior,
+    Security,
 }
 
 #[tokio::main]
@@ -70,6 +82,9 @@ async fn main() -> Result<()> {
             config.validate()?;
             Engine::new(config).run().await?;
         }
+        Command::Docs { topic } => {
+            print!("{}", docs_text(topic));
+        }
     }
     Ok(())
 }
@@ -128,12 +143,21 @@ fn resolve_config_path(config: Option<PathBuf>) -> Result<PathBuf> {
     }
 }
 
+fn docs_text(topic: DocsTopic) -> &'static str {
+    match topic {
+        DocsTopic::Config => include_str!("../docs/configuration.md"),
+        DocsTopic::Behavior => include_str!("../docs/behavior.md"),
+        DocsTopic::Security => include_str!("../docs/security.md"),
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use super::{default_rust_log, format_tracing_prefix};
+    use super::{Cli, DocsTopic, default_rust_log, docs_text, format_tracing_prefix};
     use crate::output::{
         format_output_prefix, normalize_internal_log_label, normalize_source_label,
     };
+    use clap::Parser;
     use std::sync::{Mutex, OnceLock};
 
     fn rust_log_lock() -> &'static Mutex<()> {
@@ -198,4 +222,22 @@ mod tests {
         assert!(rendered.starts_with("\u{1b}[1;"));
         assert!(rendered.ends_with(" "));
     }
+
+    #[test]
+    fn docs_text_uses_embedded_configuration_reference() {
+        let rendered = docs_text(DocsTopic::Config);
+
+        assert!(rendered.starts_with("# Configuration Reference"));
+        assert!(rendered.contains("startup_workflows"));
+    }
+
+    #[test]
+    fn cli_parses_docs_subcommand() {
+        let cli = Cli::try_parse_from(["devloop", "docs", "security"]).expect("parse cli");
+
+        match cli.command {
+            super::Command::Docs { topic } => assert!(matches!(topic, DocsTopic::Security)),
+            _ => panic!("expected docs subcommand"),
+        }
+    }
 }