auditkit 0.1.4 → 0.1.6

package/Cargo.lock

@@ -90,7 +90,7 @@ checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
 [[package]]
 name = "auditkit"
-version = "0.1.4"
+version = "0.1.6"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "auditkit"
-version = "0.1.4"
+version = "0.1.6"
 edition = "2021"
 description = "Local hybrid CLI for agency website audits."
 license = "MIT"

package/README.md

@@ -1,111 +1,98 @@
 # Audit Kit
 
-Local hybrid CLI for agency website audits.
+Fast local website audits for freelancers and agencies. Run HTML, security, Lighthouse, and report-generation workflows from one small CLI.
 
-Rust runs the core workflow: audit folders, quick HTML checks, security checks, and report generation. Node is used only for Lighthouse.
+```text
+╭──────────────────────── Audit Kit ────────────────────────╮
+│ ak check        guided one-off website audit               │
+│ ak check --save choose where the audit files should go     │
+│ ak new          create a reusable client workspace          │
+╰────────────────────────────────────────────────────────────╯
+```
 
 ## Install
 
-From this project folder:
-
 ```bash
-npm install
-cargo build
-npm link
+npm install -g auditkit
+# or
+bun add -g auditkit
 ```
 
-Prerequisites:
+Requirements:
 
-- Rust toolchain with `cargo`
+- Rust + `cargo`
 - Node.js 24+
-- Helium, Chrome, Chromium, Brave, or Edge for Lighthouse
+- Chrome, Chromium, Brave, Edge, or Helium for Lighthouse
 
-## Basic Workflow
+## Quick start
 
 ```bash
-ak new
-ak inspect latest
-ak report latest
+ak check
 ```
 
-`ak new` creates a workspace in `audits/`. Fill in:
-
-- `findings.md`
-- `workspace.md`
-
-Then `ak report latest` creates:
-
-- `final-report.md`
-- `client-email.md`
+Audit Kit asks for the website, runs the check, then asks where to save the markdown files.
 
-## Commands
+```text
+› Website URL (https://example.com) https://example.com
+✓ Fetching website and reading HTML
+› Save this check as markdown? (Y/n) y
+› Save folder (./auditkit-example-com) ~/audits/example
+✓ saved /Users/you/audits/example/automated-check.md
+```
 
-- `ak new` - create a new audit folder
-- `ak check latest` - run automated feedback for the latest audit and save it
-- `ak security latest` - run security header check for the latest audit and save it
-- `ak lighthouse latest` - run Lighthouse for the latest audit and save markdown + JSON
-- `ak inspect latest` - run automated feedback, security, and Lighthouse
-- `ak check <url>` - fetch a website and print quick feedback
-- `ak security <url>` - fetch a website and print security feedback
-- `ak lighthouse <url>` - run Lighthouse for a website
-- `ak check <url> --save <audit-folder>` - fetch a website and save feedback into an audit
-- `ak security <url> --save <audit-folder>` - save security feedback into an audit
-- `ak lighthouse <url> --save <audit-folder>` - save Lighthouse output into an audit
-- `ak report latest` - generate `final-report.md` and `client-email.md`
-- `ak list` - list existing audits
-
-Long form also works:
-
-- `auditkit new`
-- `auditkit check latest`
-- `auditkit report latest`
-- `auditkit list`
-
-NPM scripts:
-
-- `npm run audit -- new` - create a new audit folder
-- `npm run audit -- check latest` - run automated feedback for the latest audit and save it
-- `npm run audit -- check <url>` - fetch a website and print quick feedback
-- `npm run audit -- check <url> --save <audit-folder>` - fetch a website and save feedback into an audit
-- `npm run audit -- report latest` - generate `final-report.md` and `client-email.md`
-- `npm run audit -- list` - list existing audits
-
-## Quick Website Check
+## Save anywhere
 
 ```bash
-ak check https://example.com
+ak check https://example.com --save ~/audits/example
+ak security https://example.com --save ~/audits/example
+ak lighthouse https://example.com --save ~/audits/example
+ak inspect https://example.com --save ~/audits/example
 ```
 
-The check is intentionally lightweight. It reviews basic HTML signals:
-
-- title tag
-- meta description
-- H1 count
-- image alt text
-- viewport tag
-- canonical link
-- obvious CTA language
-- initial response time and HTML size
+Saved files use simple names:
 
-## Lighthouse Requirement
-
-`ak lighthouse` and `ak inspect` need a Chrome-family browser installed:
+```text
+~/audits/example/
+├─ automated-check.md
+├─ security-check.md
+├─ lighthouse.md
+└─ lighthouse.json
+```
 
-- Helium
-- Google Chrome
-- Chromium
-- Brave
-- Microsoft Edge
+## Full client workflow
 
-If none is installed, Lighthouse cannot run.
+```bash
+ak new
+ak inspect latest
+ak report latest
+```
 
-Audit Kit auto-detects Helium at:
+That creates an audit workspace, runs every check, then writes:
 
 ```text
-/Applications/Helium.app/Contents/MacOS/Helium
+audits/<date-client>/
+├─ workspace.md
+├─ findings.md
+├─ final-report.md
+├─ client-email.md
+└─ raw/lighthouse.json
 ```
 
-Override browser path when needed:
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `ak check` | guided HTML/SEO basics check |
+| `ak check <url> --save <folder>` | save check markdown to any folder |
+| `ak security <url> --save <folder>` | save security header audit |
+| `ak lighthouse <url> --save <folder>` | save Lighthouse markdown + JSON |
+| `ak inspect <url> --save <folder>` | run and save every automated check |
+| `ak new` | create a client audit workspace |
+| `ak inspect latest` | run all checks for the newest workspace |
+| `ak report latest` | create the final report and client email |
+| `ak list` | list audit workspaces |
+
+## Browser override
 
 ```bash
 AUDITKIT_BROWSER_PATH="/path/to/browser" ak lighthouse https://example.com
@@ -113,22 +100,9 @@ AUDITKIT_BROWSER_PATH="/path/to/browser" ak lighthouse https://example.com
 
 ## Development
 
-Run all tests:
-
 ```bash
 npm test
-```
-
-Rust-only:
-
-```bash
 cargo test
 ```
 
-Node Lighthouse helper only:
-
-```bash
-npm run test:node
-```
-
 Architecture notes live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditkit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Local hybrid CLI for agency website audits.",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,6 @@
     "audit:security": "cargo run --quiet -- security",
     "audit:lighthouse": "cargo run --quiet -- lighthouse",
     "audit:inspect": "cargo run --quiet -- inspect",
-    "postinstall": "node scripts/auditkit/postinstall.mjs",
     "test": "npm run test:node && npm run test:rust",
     "test:node": "node --test",
     "test:rust": "cargo test"

package/scripts/auditkit/ak

@@ -19,6 +19,23 @@ SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
 BINARY="$ROOT_DIR/target/debug/auditkit"
 
+if [ -z "${CI:-}" ] && [ -z "${AUDITKIT_SKIP_WELCOME:-}" ]; then
+  if [ -n "${XDG_STATE_HOME:-}" ]; then
+    WELCOME_DIR="$XDG_STATE_HOME/auditkit"
+  elif [ -n "${HOME:-}" ]; then
+    WELCOME_DIR="$HOME/.local/state/auditkit"
+  else
+    WELCOME_DIR=""
+  fi
+
+  if [ -n "$WELCOME_DIR" ] && [ ! -f "$WELCOME_DIR/welcome-v0.1.6" ]; then
+    if command -v node >/dev/null 2>&1; then
+      node "$ROOT_DIR/scripts/auditkit/postinstall.mjs" || true
+    fi
+    mkdir -p "$WELCOME_DIR" 2>/dev/null && : >"$WELCOME_DIR/welcome-v0.1.6" 2>/dev/null || true
+  fi
+fi
+
 if [ ! -x "$BINARY" ]; then
   cargo build --manifest-path "$ROOT_DIR/Cargo.toml" >/dev/null
 fi

package/scripts/auditkit/lighthouse.test.mjs

@@ -5,7 +5,7 @@ import {
   formatLighthouseReport,
   summarizeLighthouse,
 } from "./lighthouse-runner.mjs";
-import { shouldShowWelcome, welcomeMessage } from "./postinstall.mjs";
+import { shouldShowWelcome, showWelcome, welcomeMessage } from "./postinstall.mjs";
 
 const lhr = {
   finalDisplayedUrl: "https://example.com/",
@@ -83,8 +83,8 @@ test("postinstall welcome explains first commands", () => {
   const plainMessage = welcomeMessage({ NO_COLOR: "1" });
 
   assert.match(message, /Audit Kit/);
-  assert.match(message, /ak new/);
-  assert.match(message, /ak inspect latest/);
+  assert.match(message, /ak check/);
+  assert.match(message, /ak check --save/);
   assert.match(message, /\x1b\[/);
   assert.doesNotMatch(plainMessage, /\x1b\[/);
   assert.match(plainMessage, /Audit Kit/);
@@ -93,3 +93,14 @@ test("postinstall welcome explains first commands", () => {
   assert.equal(shouldShowWelcome({ AUDITKIT_SKIP_WELCOME: "1" }), false);
   assert.equal(shouldShowWelcome({ npm_config_loglevel: "silent" }), false);
 });
+
+test("postinstall writes welcome to the provided stream", () => {
+  let output = "";
+  showWelcome({ write: (value) => (output += value) }, { NO_COLOR: "1" });
+  assert.match(output, /Audit Kit/);
+  assert.match(output, /ak check/);
+
+  output = "";
+  showWelcome({ write: (value) => (output += value) }, { CI: "true" });
+  assert.equal(output, "");
+});

package/scripts/auditkit/postinstall.mjs

@@ -14,10 +14,10 @@ export function welcomeMessage(env = process.env) {
     divider(colors),
     line(`   ${paint("Try first", 97, colors)}                                                `, colors),
     line("                                                            ", colors),
-    commandLine("ak new", "create an audit workspace", colors),
-    commandLine("ak inspect latest", "run check, security, Lighthouse", colors),
-    commandLine("ak report latest", "generate report + client email", colors),
-    commandLine("ak list", "show saved audits", colors),
+    commandLine("ak check", "guided website check", colors),
+    commandLine("ak check --save", "choose a save folder", colors),
+    commandLine("ak new", "create a full audit", colors),
+    commandLine("ak inspect latest", "run every check", colors),
     line("                                                            ", colors),
   ];
 
@@ -31,12 +31,18 @@ export function welcomeMessage(env = process.env) {
   ].join("\n");
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href && shouldShowWelcome()) {
-  console.log(welcomeMessage());
+export function showWelcome(stream = process.stderr, env = process.env) {
+  if (shouldShowWelcome(env)) {
+    stream.write(`${welcomeMessage(env)}\n`);
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  showWelcome();
 }
 
 function commandLine(command, description, colors) {
-  return line(`   ${paint(command.padEnd(18), 36, colors)} ${paint(description.padEnd(34), 90, colors)}    `, colors);
+  return line(`   ${paint(command.padEnd(24).slice(0, 24), 36, colors)} ${paint(description.padEnd(28).slice(0, 28), 90, colors)}    `, colors);
 }
 
 function line(content, colors) {

package/src/main.rs

@@ -1,4 +1,8 @@
-use std::{fs, process};
+use std::{
+    env, fs,
+    path::{Path, PathBuf},
+    process,
+};
 
 use anyhow::{Context, Result};
 use auditkit::audit::{slugify, split_comma_list, AuditInput};
@@ -10,6 +14,7 @@ use auditkit::ui;
 use auditkit::workspace::Workspace;
 use chrono::Local;
 use clap::{Parser, Subcommand};
+use url::Url;
 
 #[derive(Parser)]
 #[command(name = "ak", about = "Audit Kit: small agency website audit workflow")]
@@ -23,28 +28,48 @@ enum Command {
     New,
     List,
     Check {
-        target: String,
-        #[arg(long)]
-        save: Option<String>,
+        target: Option<String>,
+        #[arg(long, value_name = "FOLDER", num_args = 0..=1)]
+        save: Option<Option<String>>,
     },
     Security {
         target: Option<String>,
-        #[arg(long)]
-        save: Option<String>,
+        #[arg(long, value_name = "FOLDER", num_args = 0..=1)]
+        save: Option<Option<String>>,
     },
     Lighthouse {
         target: Option<String>,
-        #[arg(long)]
-        save: Option<String>,
+        #[arg(long, value_name = "FOLDER", num_args = 0..=1)]
+        save: Option<Option<String>>,
     },
     Inspect {
         target: Option<String>,
+        #[arg(long, value_name = "FOLDER", num_args = 0..=1)]
+        save: Option<Option<String>>,
     },
     Report {
         target: Option<String>,
     },
 }
 
+#[derive(Debug, Clone, Copy)]
+struct SaveRequest<'a> {
+    explicit: bool,
+    value: Option<&'a str>,
+}
+
+#[derive(Debug, Clone)]
+enum SaveDestination {
+    Audit(String),
+    Directory(PathBuf),
+}
+
+#[derive(Debug, Clone)]
+struct TargetInput {
+    value: String,
+    prompted: bool,
+}
+
 fn main() {
     if let Err(error) = run() {
         ui::error(error);
@@ -59,14 +84,18 @@ fn run() -> Result<()> {
     match cli.command {
         Some(Command::New) => new_audit(&workspace),
         Some(Command::List) => list_audits(&workspace),
-        Some(Command::Check { target, save }) => check(&workspace, &target, save.as_deref()),
+        Some(Command::Check { target, save }) => {
+            check(&workspace, target.as_deref(), save_request(&save))
+        }
         Some(Command::Security { target, save }) => {
-            security_check(&workspace, target.as_deref(), save.as_deref())
+            security_check(&workspace, target.as_deref(), save_request(&save))
         }
         Some(Command::Lighthouse { target, save }) => {
-            lighthouse_check(&workspace, target.as_deref(), save.as_deref())
+            lighthouse_check(&workspace, target.as_deref(), save_request(&save))
+        }
+        Some(Command::Inspect { target, save }) => {
+            inspect(&workspace, target.as_deref(), save_request(&save))
         }
-        Some(Command::Inspect { target }) => inspect(&workspace, target.as_deref()),
         Some(Command::Report { target }) => generate_report(&workspace, target.as_deref()),
         None => {
             ui::help();
@@ -75,6 +104,23 @@ fn run() -> Result<()> {
     }
 }
 
+fn save_request(value: &Option<Option<String>>) -> SaveRequest<'_> {
+    match value {
+        None => SaveRequest {
+            explicit: false,
+            value: None,
+        },
+        Some(None) => SaveRequest {
+            explicit: true,
+            value: None,
+        },
+        Some(Some(value)) => SaveRequest {
+            explicit: true,
+            value: Some(value),
+        },
+    }
+}
+
 fn new_audit(workspace: &Workspace) -> Result<()> {
     let answers = ui::collect_audit_input()?;
 
@@ -113,53 +159,63 @@ fn list_audits(workspace: &Workspace) -> Result<()> {
     Ok(())
 }
 
-fn check(workspace: &Workspace, target: &str, save: Option<&str>) -> Result<()> {
-    if looks_like_url(target) {
+fn check(workspace: &Workspace, target: Option<&str>, save: SaveRequest<'_>) -> Result<()> {
+    let target = target_or_prompt("Website URL", "https://example.com", target)?;
+    ui::section("Website Check");
+    ui::step(1, "Website", &target.value);
+
+    if looks_like_url(&target.value) {
         let result = ui::with_task("Fetching website and reading HTML", || {
-            html_check::check_url(target)
+            html_check::check_url(&target.value)
         })?;
         println!("{}", html_check::format_cli(&result));
-        if let Some(folder) = save {
-            let folder = workspace.resolve_target(Some(folder))?;
-            let path = workspace.update_workspace_section(
-                &folder,
-                "Automated Check",
-                &html_check::format_markdown(&result),
-            )?;
-            ui::saved(path.display());
+        if let Some(destination) = save_destination_for_result(
+            workspace,
+            save,
+            &target.value,
+            "Save this check as markdown?",
+            target.prompted,
+        )? {
+            save_html_result(workspace, &destination, &result)?;
         }
         return Ok(());
     }
 
-    let folder = workspace.resolve_target(Some(target))?;
+    let folder = workspace.resolve_target(Some(&target.value))?;
     let website = audit_website(workspace, &folder)?;
     let result = ui::with_task("Fetching website and reading HTML", || {
         html_check::check_url(&website)
     })?;
     println!("{}", html_check::format_cli(&result));
-    let path = workspace.update_workspace_section(
-        &folder,
-        "Automated Check",
-        &html_check::format_markdown(&result),
-    )?;
-    ui::saved(path.display());
+    let destination = if save.explicit {
+        resolve_save_destination(workspace, save.value, &website)?
+    } else {
+        SaveDestination::Audit(folder)
+    };
+    save_html_result(workspace, &destination, &result)?;
     Ok(())
 }
 
-fn security_check(workspace: &Workspace, target: Option<&str>, save: Option<&str>) -> Result<()> {
+fn security_check(
+    workspace: &Workspace,
+    target: Option<&str>,
+    save: SaveRequest<'_>,
+) -> Result<()> {
     let target = target.unwrap_or("latest");
+    ui::section("Security Check");
+    ui::step(1, "Target", target);
 
     if looks_like_url(target) {
         let result = ui::with_task("Checking security headers", || security::check_url(target))?;
         println!("{}", security::format_cli(&result));
-        if let Some(folder) = save {
-            let folder = workspace.resolve_target(Some(folder))?;
-            let path = workspace.update_workspace_section(
-                &folder,
-                "Security Check",
-                &security::format_markdown(&result),
-            )?;
-            ui::saved(path.display());
+        if let Some(destination) = save_destination_for_result(
+            workspace,
+            save,
+            target,
+            "Save this security check as markdown?",
+            false,
+        )? {
+            save_security_result(workspace, &destination, &result)?;
         }
         return Ok(());
     }
@@ -170,52 +226,226 @@ fn security_check(workspace: &Workspace, target: Option<&str>, save: Option<&str
         security::check_url(&website)
     })?;
     println!("{}", security::format_cli(&result));
-    let path = workspace.update_workspace_section(
-        &folder,
-        "Security Check",
-        &security::format_markdown(&result),
-    )?;
-    ui::saved(path.display());
+    let destination = if save.explicit {
+        resolve_save_destination(workspace, save.value, &website)?
+    } else {
+        SaveDestination::Audit(folder)
+    };
+    save_security_result(workspace, &destination, &result)?;
     Ok(())
 }
 
-fn lighthouse_check(workspace: &Workspace, target: Option<&str>, save: Option<&str>) -> Result<()> {
+fn lighthouse_check(
+    workspace: &Workspace,
+    target: Option<&str>,
+    save: SaveRequest<'_>,
+) -> Result<()> {
     let target = target.unwrap_or("latest");
+    ui::section("Lighthouse Check");
+    ui::step(1, "Target", target);
 
     if looks_like_url(target) {
-        let save_folder = save
-            .map(|folder| workspace.resolve_target(Some(folder)))
-            .transpose()?;
-        let temp_dir = save_folder.as_ref().map(|_| lighthouse_temp_dir(workspace));
-        if let Some(folder) = &temp_dir {
-            fs::create_dir_all(folder)?;
-        }
-        let paths = ui::with_task("Running Lighthouse in Helium", || {
-            lighthouse::run_lighthouse(&workspace.root, target, temp_dir.as_deref())
-        })?;
-        print_lighthouse_output(&paths.cli_output);
-        if let Some(folder) = save_folder {
-            save_lighthouse_summary(workspace, &folder, &paths)?;
-        } else {
-            ui::saved(paths.markdown_path.display());
-            ui::saved(paths.json_path.display());
-        }
-        if let Some(folder) = temp_dir {
-            let _ = fs::remove_dir_all(folder);
-        }
+        let destination = save_destination_for_result(
+            workspace,
+            save,
+            target,
+            "Save this Lighthouse report?",
+            false,
+        )?;
+        run_lighthouse_for_url(workspace, target, destination.as_ref())?;
+        return Ok(());
+    }
+
+    let folder = workspace.resolve_target(Some(target))?;
+    let website = audit_website(workspace, &folder)?;
+    let destination = if save.explicit {
+        resolve_save_destination(workspace, save.value, &website)?
+    } else {
+        SaveDestination::Audit(folder)
+    };
+    run_lighthouse_for_url(workspace, &website, Some(&destination))?;
+    Ok(())
+}
+
+fn inspect(workspace: &Workspace, target: Option<&str>, save: SaveRequest<'_>) -> Result<()> {
+    let target = target.unwrap_or("latest");
+    ui::section("Inspect");
+    ui::step(1, "Target", target);
+
+    if looks_like_url(target) {
+        let destination =
+            save_destination_for_result(workspace, save, target, "Save all audit files?", true)?;
+        inspect_url(workspace, target, destination.as_ref())?;
         return Ok(());
     }
 
     let folder = workspace.resolve_target(Some(target))?;
     let website = audit_website(workspace, &folder)?;
-    let temp_dir = lighthouse_temp_dir(workspace);
-    fs::create_dir_all(&temp_dir)?;
-    let paths = ui::with_task("Running Lighthouse in Helium", || {
-        lighthouse::run_lighthouse(&workspace.root, &website, Some(&temp_dir))
+    if save.explicit {
+        let destination = resolve_save_destination(workspace, save.value, &website)?;
+        inspect_url(workspace, &website, Some(&destination))?;
+    } else {
+        ui::bullet(&format!("Running checks for {folder}"));
+        check(workspace, Some(&folder), SaveRequest::none())?;
+        security_check(workspace, Some(&folder), SaveRequest::none())?;
+        lighthouse_check(workspace, Some(&folder), SaveRequest::none())?;
+    }
+    Ok(())
+}
+
+fn inspect_url(
+    workspace: &Workspace,
+    target: &str,
+    destination: Option<&SaveDestination>,
+) -> Result<()> {
+    ui::step(2, "HTML", "title, meta, H1, images, CTA signals");
+    let html = ui::with_task("Fetching website and reading HTML", || {
+        html_check::check_url(target)
+    })?;
+    println!("{}", html_check::format_cli(&html));
+    if let Some(destination) = destination {
+        save_html_result(workspace, destination, &html)?;
+    }
+
+    ui::step(3, "Security", "headers and browser protections");
+    let security = ui::with_task("Checking security headers", || security::check_url(target))?;
+    println!("{}", security::format_cli(&security));
+    if let Some(destination) = destination {
+        save_security_result(workspace, destination, &security)?;
+    }
+
+    ui::step(4, "Lighthouse", "performance, accessibility, SEO");
+    run_lighthouse_for_url(workspace, target, destination)?;
+    Ok(())
+}
+
+impl<'a> SaveRequest<'a> {
+    fn none() -> Self {
+        Self {
+            explicit: false,
+            value: None,
+        }
+    }
+}
+
+fn save_destination_for_result(
+    workspace: &Workspace,
+    save: SaveRequest<'_>,
+    target: &str,
+    prompt_label: &str,
+    offer_prompt: bool,
+) -> Result<Option<SaveDestination>> {
+    if save.explicit {
+        return resolve_save_destination(workspace, save.value, target).map(Some);
+    }
+
+    if offer_prompt && ui::can_prompt() && ui::confirm(prompt_label, true)? {
+        return resolve_save_destination(workspace, None, target).map(Some);
+    }
+
+    Ok(None)
+}
+
+fn resolve_save_destination(
+    workspace: &Workspace,
+    value: Option<&str>,
+    target: &str,
+) -> Result<SaveDestination> {
+    let raw = match value {
+        Some(value) if !value.trim().is_empty() => value.trim().to_string(),
+        _ if ui::can_prompt() => {
+            ui::prompt_with_default("Save folder", &suggested_save_folder(target))?
+        }
+        _ => anyhow::bail!("Missing save folder. Use `--save <folder>`."),
+    };
+
+    let folders = workspace.list_audits()?;
+    if raw == "latest" {
+        let folder = folders
+            .last()
+            .with_context(|| "No audits found. Use a folder path such as `--save ./audit`.")?;
+        return Ok(SaveDestination::Audit(folder.to_string()));
+    }
+    if folders.iter().any(|folder| folder == &raw) {
+        return Ok(SaveDestination::Audit(raw));
+    }
+
+    Ok(SaveDestination::Directory(expand_path(&raw)?))
+}
+
+fn save_html_result(
+    workspace: &Workspace,
+    destination: &SaveDestination,
+    result: &html_check::HtmlCheck,
+) -> Result<()> {
+    let markdown = html_check::format_markdown(result);
+    match destination {
+        SaveDestination::Audit(folder) => {
+            let path = workspace.update_workspace_section(folder, "Automated Check", &markdown)?;
+            ui::saved(path.display());
+        }
+        SaveDestination::Directory(folder) => {
+            let path = write_save_file(folder, "automated-check.md", &markdown)?;
+            ui::saved(path.display());
+        }
+    }
+    Ok(())
+}
+
+fn save_security_result(
+    workspace: &Workspace,
+    destination: &SaveDestination,
+    result: &security::SecurityCheck,
+) -> Result<()> {
+    let markdown = security::format_markdown(result);
+    match destination {
+        SaveDestination::Audit(folder) => {
+            let path = workspace.update_workspace_section(folder, "Security Check", &markdown)?;
+            ui::saved(path.display());
+        }
+        SaveDestination::Directory(folder) => {
+            let path = write_save_file(folder, "security-check.md", &markdown)?;
+            ui::saved(path.display());
+        }
+    }
+    Ok(())
+}
+
+fn run_lighthouse_for_url(
+    workspace: &Workspace,
+    target: &str,
+    destination: Option<&SaveDestination>,
+) -> Result<()> {
+    let temp_dir = destination
+        .filter(|destination| matches!(destination, SaveDestination::Audit(_)))
+        .map(|_| lighthouse_temp_dir(workspace));
+    let output_dir = match destination {
+        Some(SaveDestination::Directory(folder)) => Some(folder.as_path()),
+        Some(SaveDestination::Audit(_)) => temp_dir.as_deref(),
+        None => None,
+    };
+
+    if let Some(folder) = output_dir {
+        fs::create_dir_all(folder)?;
+    }
+
+    let paths = ui::with_task("Running Lighthouse", || {
+        lighthouse::run_lighthouse(&workspace.root, target, output_dir)
     })?;
     print_lighthouse_output(&paths.cli_output);
-    save_lighthouse_summary(workspace, &folder, &paths)?;
-    let _ = fs::remove_dir_all(temp_dir);
+
+    match destination {
+        Some(SaveDestination::Audit(folder)) => save_lighthouse_summary(workspace, folder, &paths)?,
+        Some(SaveDestination::Directory(_)) | None => {
+            ui::saved(paths.markdown_path.display());
+            ui::saved(paths.json_path.display());
+        }
+    }
+
+    if let Some(folder) = temp_dir {
+        let _ = fs::remove_dir_all(folder);
+    }
+
     Ok(())
 }
 
@@ -240,7 +470,14 @@ fn save_lighthouse_summary(
     Ok(())
 }
 
-fn lighthouse_temp_dir(workspace: &Workspace) -> std::path::PathBuf {
+fn write_save_file(folder: &Path, filename: &str, content: &str) -> Result<PathBuf> {
+    fs::create_dir_all(folder).with_context(|| format!("Creating {}", folder.display()))?;
+    let path = folder.join(filename);
+    fs::write(&path, content).with_context(|| format!("Writing {}", path.display()))?;
+    Ok(path)
+}
+
+fn lighthouse_temp_dir(workspace: &Workspace) -> PathBuf {
     workspace.root.join("target").join(format!(
         "auditkit-lighthouse-{}-{}",
         process::id(),
@@ -248,16 +485,6 @@ fn lighthouse_temp_dir(workspace: &Workspace) -> std::path::PathBuf {
     ))
 }
 
-fn inspect(workspace: &Workspace, target: Option<&str>) -> Result<()> {
-    let folder = workspace.resolve_target(target)?;
-    ui::section("Inspect");
-    ui::bullet(&format!("Running checks for {folder}"));
-    check(workspace, &folder, None)?;
-    security_check(workspace, Some(&folder), None)?;
-    lighthouse_check(workspace, Some(&folder), None)?;
-    Ok(())
-}
-
 fn generate_report(workspace: &Workspace, target: Option<&str>) -> Result<()> {
     let folder = workspace.resolve_target(target)?;
     let (report_path, email_path) =
@@ -280,6 +507,54 @@ fn audit_website(workspace: &Workspace, folder: &str) -> Result<String> {
     Ok(parsed.website)
 }
 
+fn target_or_prompt(label: &str, placeholder: &str, target: Option<&str>) -> Result<TargetInput> {
+    if let Some(value) = target {
+        return Ok(TargetInput {
+            value: value.to_string(),
+            prompted: false,
+        });
+    }
+
+    if ui::can_prompt() {
+        return Ok(TargetInput {
+            value: ui::prompt_required(label, placeholder)?,
+            prompted: true,
+        });
+    }
+
+    anyhow::bail!("Missing target. Use `ak check <url>` or run `ak check` in a terminal.")
+}
+
+fn suggested_save_folder(target: &str) -> String {
+    let slug = Url::parse(target)
+        .ok()
+        .and_then(|url| url.host_str().map(slugify))
+        .filter(|slug| !slug.is_empty())
+        .unwrap_or_else(|| slugify(target));
+    let slug = if slug.is_empty() { "audit" } else { &slug };
+    format!("./auditkit-{slug}")
+}
+
+fn expand_path(value: &str) -> Result<PathBuf> {
+    let path = if value == "~" {
+        home_dir().context("HOME is not set")?
+    } else if let Some(rest) = value.strip_prefix("~/") {
+        home_dir().context("HOME is not set")?.join(rest)
+    } else {
+        PathBuf::from(value)
+    };
+
+    if path.is_absolute() {
+        Ok(path)
+    } else {
+        Ok(env::current_dir()?.join(path))
+    }
+}
+
+fn home_dir() -> Option<PathBuf> {
+    env::var_os("HOME").map(PathBuf::from)
+}
+
 fn looks_like_url(value: &str) -> bool {
     value.starts_with("http://") || value.starts_with("https://") || value.contains('.')
 }

package/src/ui.rs

@@ -49,6 +49,15 @@ pub fn saved(path: impl std::fmt::Display) {
     println!("{} {}", "✓ saved".green().bold(), path);
 }
 
+pub fn step(number: usize, title: &str, detail: &str) {
+    println!(
+        "  {} {} {}",
+        format!("{number}.").cyan().bold(),
+        title.bold(),
+        detail.dimmed()
+    );
+}
+
 pub fn error(message: impl std::fmt::Display) {
     eprintln!("{} {}", "✕ error".red().bold(), message);
 }
@@ -145,13 +154,12 @@ pub fn help() {
         "{}",
         "├──────────────────────────────────────────────────────────────────────────┤".cyan()
     );
-    help_row("ak new", "create an audit workspace");
-    help_row("ak list", "show audit folders");
-    help_row("ak inspect latest", "run check, security, and Lighthouse");
-    help_row("ak report latest", "create final report and client email");
-    help_row("ak check <url>", "quick one-off website feedback");
-    help_row("ak security <url>", "quick one-off security check");
-    help_row("ak lighthouse <url>", "quick one-off Lighthouse check");
+    help_row("ak check", "guided website check");
+    help_row("ak check <url> --save ~/audits", "save files anywhere");
+    help_row("ak new", "create a full audit workspace");
+    help_row("ak inspect latest", "run every check for an audit");
+    help_row("ak report latest", "create report and email");
+    help_row("ak list", "show saved audit workspaces");
     println!(
         "{}",
         "╰──────────────────────────────────────────────────────────────────────────╯".cyan()
@@ -159,16 +167,20 @@ pub fn help() {
 }
 
 pub fn collect_audit_input() -> Result<NewAuditAnswers> {
-    if io::stdin().is_terminal() && io::stdout().is_terminal() {
+    if can_prompt() {
         run_form()
     } else {
         fallback_prompts()
     }
 }
 
+pub fn can_prompt() -> bool {
+    io::stdin().is_terminal() && io::stdout().is_terminal()
+}
+
 fn help_row(command: &str, description: &str) {
-    let command = format!("{command:<23}").bold();
-    let description = format!("{description:<45}").dimmed();
+    let command = format!("{command:<31}").bold();
+    let description = format!("{description:<39}").dimmed();
     println!("{}  {} {} {}", "│".cyan(), command, description, "│".cyan());
 }
 
@@ -194,6 +206,64 @@ fn prompt(label: &str) -> Result<String> {
     Ok(value.trim().to_string())
 }
 
+pub fn prompt_required(label: &str, placeholder: &str) -> Result<String> {
+    loop {
+        let suffix = if placeholder.is_empty() {
+            String::new()
+        } else {
+            format!(" {}", format!("({placeholder})").dimmed())
+        };
+        print!("{} {}{} ", "›".cyan().bold(), label.bold(), suffix);
+        io::stdout().flush()?;
+        let mut value = String::new();
+        io::stdin().read_line(&mut value)?;
+        let value = value.trim();
+        if !value.is_empty() {
+            return Ok(value.to_string());
+        }
+        println!("{}", "  Please enter a value.".yellow());
+    }
+}
+
+pub fn prompt_with_default(label: &str, default: &str) -> Result<String> {
+    print!(
+        "{} {} {} ",
+        "›".cyan().bold(),
+        label.bold(),
+        format!("({default})").dimmed()
+    );
+    io::stdout().flush()?;
+    let mut value = String::new();
+    io::stdin().read_line(&mut value)?;
+    let value = value.trim();
+    if value.is_empty() {
+        Ok(default.to_string())
+    } else {
+        Ok(value.to_string())
+    }
+}
+
+pub fn confirm(label: &str, default: bool) -> Result<bool> {
+    let hint = if default { "Y/n" } else { "y/N" };
+    loop {
+        print!(
+            "{} {} {} ",
+            "›".cyan().bold(),
+            label.bold(),
+            format!("({hint})").dimmed()
+        );
+        io::stdout().flush()?;
+        let mut value = String::new();
+        io::stdin().read_line(&mut value)?;
+        match value.trim().to_lowercase().as_str() {
+            "" => return Ok(default),
+            "y" | "yes" => return Ok(true),
+            "n" | "no" => return Ok(false),
+            _ => println!("{}", "  Type yes or no.".yellow()),
+        }
+    }
+}
+
 fn run_form() -> Result<NewAuditAnswers> {
     enable_raw_mode()?;
     let mut stdout = io::stdout();