ontoref/reflection/nulib/help.nu

# reflection/nulib/help.nu — Help text rendering for all command groups.

use ./fmt.nu *
use ./shared.nu [all-mode-files, adrs-brief]
use ../modules/store.nu [daemon-export-safe]
use ../modules/forms.nu ["forms list"]

export def help-group [group: string] {
  let cmd = ($env.ONTOREF_CALLER? | default "ontoref")
  let actor = ($env.ONTOREF_ACTOR? | default "developer")

  match $group {
    "check" | "prereqs" => {
      print ""
      fmt-header "PREREQUISITES"
      fmt-sep
      fmt-cmd $"($cmd) check" "check current actor context"
      fmt-cmd $"($cmd) check --context ci" "check CI environment"
      fmt-cmd $"($cmd) check --form <name>" "check what a specific form needs"
      fmt-cmd $"($cmd) check --severity <s>" "filter by severity"
      fmt-cmd $"($cmd) check --json" "machine-readable output"
      print ""
      fmt-aliases [
        { short: "ck", long: "check" },
      ]
    },
    "form" | "forms" => {
      print ""
      fmt-header "FORM"
      fmt-sep
      let form_items = (forms list)
      for f in $form_items {
        if $actor == "agent" {
          fmt-cmd $"nickel export reflection/forms/($f.name).ncl"
          fmt-info $f.description
        } else {
          fmt-cmd $"($cmd) form run ($f.name)" -v 1
          fmt-cmd $"($cmd) form run ($f.name) --backend web" "browser UI" -v 1
          fmt-cmd $"($cmd) form run ($f.name) --backend tui" "terminal 3-panel UI" -v 1
          fmt-info $f.description
        }
        print ""
      }
      fmt-cmd $"($cmd) form list" "list all available forms"
      fmt-cmd $"($cmd) form ls" "list forms (machine-friendly)" -v 1
      print ""
      fmt-aliases [
        { short: "fm", long: "form" },
        { short: "fm l", long: "form list" },
      ]
    },
    "mode" | "modes" => {
      print ""
      fmt-header "MODE  (operational procedures)"
      fmt-sep
      fmt-section "Inspect"
      print ""
      let mode_files = (all-mode-files)
      for f in $mode_files {
        let m = (daemon-export-safe $f)
        if $m != null {
          fmt-cmd $"($cmd) mode show ($m.id)" -v 1
          fmt-info $m.trigger
          print ""
        }
      }
      fmt-cmd $"($cmd) mode list" "list all modes"
      fmt-cmd $"($cmd) mode show <id> --fmt json|md|yaml|toml|table" "output format"
      fmt-cmd $"($cmd) mode select" "interactive selector"
      print ""
      fmt-section "Execute  (requires authorization via .ontoref/config.ncl → mode_run)"
      print ""
      fmt-cmd $"($cmd) mode run <id>" "execute mode steps with confirmation" -v 1
      fmt-cmd $"($cmd) mode run <id> --dry-run" "show steps without executing" -v 1
      fmt-cmd $"($cmd) mode run <id> --yes" "skip per-step confirmation" -v 1
      print ""
      fmt-info "Authorization rules: .ontoref/config.ncl → mode_run.rules"
      fmt-info "Each rule matches on { profile, actor, mode_id } — first match wins."
      fmt-info "Steps with actor=Human skip for agent/ci, and vice versa."
      print ""
      fmt-aliases [
        { short: "md", long: "mode" },
        { short: "md l", long: "mode list" },
        { short: "md s", long: "mode show <id>" },
        { short: "md run", long: "mode run <id>" },
      ]
    },
    "adr" | "adrs" => {
      let brief = adrs-brief
      let adr_status = $"($brief.accepted) Accepted / ($brief.superseded) Superseded / ($brief.proposed) Proposed"
      print ""
      fmt-header $"ADRs  (fmt-badge $adr_status)"
      fmt-sep
      fmt-cmd $"($cmd) adr list" "list all ADRs with status" -v 1
      fmt-cmd $"($cmd) adr list --fmt <fmt>" "fmt: table* | md | json | yaml | toml" -v 1
      fmt-cmd $"($cmd) adr validate" "run Hard constraint checks" -v 1
      fmt-cmd $"($cmd) adr accept <id>" "Proposed → Accepted (patches file in-place)" -v 1
      fmt-cmd $"($cmd) adr show" "interactive ADR browser" -v 1
      fmt-cmd $"($cmd) adr show -i" "interactive ADR browser [explicit]" -v 1
      fmt-cmd $"($cmd) adr show <id>" "show a specific ADR" -v 1
      fmt-cmd $"($cmd) adr show <id> --fmt <fmt>" "fmt: md* | table | json | yaml | toml" -v 1
      print ""
      fmt-section "CONSTRAINTS"
      print ""
      fmt-cmd $"($cmd) constraint" "show active Hard constraints"
      fmt-cmd $"($cmd) constraint --fmt <fmt>" "fmt: table* | md | json | yaml | toml"
      print ""
      fmt-aliases [
        { short: "ad",    long: "adr" },
        { short: "ad l",  long: "adr list" },
        { short: "ad a",  long: "adr accept <id>" },
        { short: "ad s",  long: "adr show [id]" },
      ]
    },
    "register" => {
      print ""
      fmt-header "REGISTER"
      fmt-sep
      fmt-cmd $"($cmd) register" "record change → CHANGELOG + ADR + ontology + mode"
      fmt-cmd $"($cmd) register --backend web" "same, with browser UI"
      fmt-cmd $"($cmd) register --backend tui" "same, with terminal 3-panel UI"
      print ""
      fmt-info "Workflow: select change type → fill form → generates:"
      fmt-info "  CHANGELOG entry, ADR update, ontology patch, mode trigger"
      print ""
      fmt-aliases [
        { short: "rg", long: "register" },
      ]
    },
    "backlog" => {
      print ""
      fmt-header "BACKLOG"
      fmt-sep
      fmt-cmd $"($cmd) backlog roadmap" "roadmap: state dimensions + open items by priority" -v 1
      fmt-cmd $"($cmd) backlog list" "open backlog items" -v 1
      fmt-cmd $"($cmd) backlog list --status <s>" "filter: Open | InProgress | Done | Cancelled" -v 1
      fmt-cmd $"($cmd) backlog list --kind <k>" "filter: Todo | Wish | Idea | Bug | Debt" -v 1
      fmt-cmd $"($cmd) backlog list --fmt <fmt>" "fmt: table* | md | json | yaml | toml" -v 1
      fmt-cmd $"($cmd) backlog show <id>" "show full item" -v 1
      fmt-cmd $"($cmd) backlog add <title>" "create new item" -v 1
      fmt-cmd $"($cmd) backlog add <title> --kind <k> --priority <p> --detail <d>" -v 1
      fmt-cmd $"($cmd) backlog done <id>" "mark item Done" -v 1
      fmt-cmd $"($cmd) backlog cancel <id>" "mark item Cancelled" -v 1
      fmt-cmd $"($cmd) backlog promote <id>" "show graduation path → ADR | mode | state" -v 1
      print ""
      fmt-aliases [
        { short: "bkl",    long: "backlog" },
        { short: "bkl r",  long: "backlog roadmap" },
        { short: "bkl l",  long: "backlog list" },
        { short: "bkl p",  long: "backlog promote <id>" },
      ]
    },
    "config" => {
      print ""
      fmt-header "CONFIG PROFILES  (sealed immutable states)"
      fmt-sep
      fmt-section "Read"
      print ""
      fmt-cmd $"($cmd) config show <profile>" "display active values + current seal" -v 1
      fmt-cmd $"($cmd) config show <profile> --fmt json" -v 1
      fmt-cmd $"($cmd) config history <profile>" "list sealed cfg-NNN entries" -v 1
      fmt-cmd $"($cmd) config diff <profile> <from> <to>" "diff values_snapshot between two seals" -v 1
      print ""
      fmt-section "Verify"
      print ""
      fmt-cmd $"($cmd) config verify <profile>" "sha256 drift check (current vs seal)" -v 1
      fmt-cmd $"($cmd) config audit" "verify all profiles in manifest" -v 1
      print ""
      fmt-section "Write"
      print ""
      fmt-cmd $"($cmd) config apply <profile>" "seal current values → cfg-NNN history entry" -v 1
      fmt-cmd $"($cmd) config apply <profile> --adr <id> --pr <id> --bug <id> --note <msg>" -v 1
      fmt-cmd $"($cmd) config rollback <profile> <cfg-id>" "restore values (hash-verified)" -v 1
      print ""
      fmt-aliases [
        { short: "cfg", long: "config" },
      ]
    },
    "sync" => {
      print ""
      fmt-header "SYNC  (ontology↔code synchronization)"
      fmt-sep
      fmt-cmd $"($cmd) sync scan" "analyze project structure" -v 1
      fmt-cmd $"($cmd) sync diff" "compare scan against .ontology/core.ncl" -v 1
      fmt-cmd $"($cmd) sync diff --quick" "fast diff (skip expensive exports)" -v 1
      fmt-cmd $"($cmd) sync propose" "generate NCL patches for drift" -v 1
      fmt-cmd $"($cmd) sync apply" "apply changes with confirmation" -v 1
      fmt-cmd $"($cmd) sync state" "compare state.ncl dimensions vs reality" -v 1
      fmt-cmd $"($cmd) sync audit" "full audit: nodes + ADRs + gates + state" -v 1
      fmt-cmd $"($cmd) sync audit --strict" "exit 1 on MISSING/STALE/BROKEN (for CI)" -v 1
      fmt-cmd $"($cmd) sync audit --quick" "fast audit (skip API surface)" -v 1
      fmt-cmd $"($cmd) sync audit --fmt json" "structured output (for agents)" -v 1
      fmt-cmd $"($cmd) sync watch" "bacon-based continuous drift detection" -v 1
      print ""
    },
    "coder" => {
      print ""
      fmt-header "CODER  (.coder/ process memory management)"
      fmt-sep
      fmt-cmd $"($cmd) coder init <author>" "initialize author workspace" -v 1
      fmt-cmd $"($cmd) coder init <author> --actor <a> --model <m>" -v 1
      print ""
      fmt-section "Record structured JSON entries:"
      print ""
      fmt-cmd $"($cmd) coder record <author> <content> --title <t> --kind <k> --category <c>" -v 1
      fmt-cmd $"($cmd) coder record <author> <content> --tags [t1,t2] --relates_to [n1] --trigger <why>" -v 1
      print ""
      fmt-section "Query:"
      print ""
      fmt-cmd $"($cmd) coder log" "all entries across authors" -v 1
      fmt-cmd $"($cmd) coder log --author <a>" "filter by author" -v 1
      fmt-cmd $"($cmd) coder log --tag <t> --domain <d> --kind <k>" -v 1
      fmt-cmd $"($cmd) coder export --format json|jsonl|csv" -v 1
      print ""
      fmt-section "Markdown triage:"
      print ""
      fmt-cmd $"($cmd) coder triage <author>" "classify inbox/ files → categories" -v 1
      fmt-cmd $"($cmd) coder triage <author> -n" "dry-run" -v 1
      fmt-cmd $"($cmd) coder triage <author> -i" "interactive" -v 1
      print ""
      fmt-section "Lifecycle:"
      print ""
      fmt-cmd $"($cmd) coder ls <author>" "list files by category" -v 1
      fmt-cmd $"($cmd) coder search <pattern>" "search across all .coder/" -v 1
      fmt-cmd $"($cmd) coder publish <author> <cat>" "promote to general/" -v 1
      fmt-cmd $"($cmd) coder graduate <source_cat>" "copy to committed path" -v 1
      fmt-cmd $"($cmd) coder authors" "list all author workspaces" -v 1
      print ""
      fmt-aliases [
        { short: "cod", long: "coder" },
      ]
    },
    "manifest" => {
      print ""
      fmt-header "MANIFEST  (operational modes + publication services)"
      fmt-sep
      fmt-info "Reads .ontology/manifest.ncl from the project."
      print ""
      fmt-section "Modes:"
      print ""
      fmt-cmd $"($cmd) manifest mode <id>" "switch mode (runs pre/post activate)" -v 1
      fmt-cmd $"($cmd) manifest mode <id> -n" "dry-run" -v 1
      fmt-cmd $"($cmd) manifest mode list" "list available modes" -v 1
      print ""
      fmt-section "Publish:"
      print ""
      fmt-cmd $"($cmd) manifest publish <id>" "run publication workflow" -v 1
      fmt-cmd $"($cmd) manifest publish <id> -n" "dry-run" -v 1
      fmt-cmd $"($cmd) manifest publish <id> -y" "skip confirmation" -v 1
      fmt-cmd $"($cmd) manifest publish list" "list publication services" -v 1
      print ""
      fmt-section "Info:"
      print ""
      fmt-cmd $"($cmd) manifest layers" "show all layers" -v 1
      fmt-cmd $"($cmd) manifest layers --mode <id>" "show visibility for a mode" -v 1
      fmt-cmd $"($cmd) manifest consumers" "show consumption modes" -v 1
      print ""
      fmt-aliases [
        { short: "mf", long: "manifest" },
      ]
    },
    "describe" => {
      print ""
      fmt-header "DESCRIBE  (project self-knowledge)"
      fmt-sep
      fmt-info "Query the project from any perspective. Aggregates ontology,"
      fmt-info "ADRs, modes, manifest, justfiles, .claude, and CI config."
      print ""
      fmt-section "Search the ontology graph"
      print ""
      fmt-cmd $"($cmd) s <term>" "search + interactive selector with detail" -v 1
      fmt-cmd $"($cmd) s <term> --level Project" "filter by level: Axiom | Tension | Practice | Project" -v 1
      fmt-cmd $"($cmd) s <term> --fmt <fmt>" "fmt: text* | json (j) | yaml (y) | toml (t) | md (m)" -v 1
      fmt-cmd $"($cmd) s <term> --clip" "copy output to clipboard, strips ANSI" -v 1
      fmt-cmd $"($cmd) s <term> --fmt json --clip" "copy JSON to clipboard" -v 1
      fmt-info "1 result → show detail directly. N results → pick, explore, jump, repeat."
      fmt-info "Detail includes: description, artifacts, connections, usage examples."
      print ""
      fmt-section "What IS this project?"
      print ""
      fmt-cmd $"($cmd) describe project" "philosophy, axioms, state, gates" -v 1
      fmt-cmd $"($cmd) describe project --actor agent" "optimized for agent consumption" -v 1
      fmt-cmd $"($cmd) describe project --fmt json" "machine-readable" -v 1
      print ""
      fmt-section "What can I DO?"
      print ""
      fmt-cmd $"($cmd) describe capabilities" "just modules, modes, commands, .claude" -v 1
      fmt-cmd $"($cmd) describe capabilities --actor ci" "filtered for CI perspective" -v 1
      print ""
      fmt-section "What can I NOT do?"
      print ""
      fmt-cmd $"($cmd) describe constraints" "invariants, Hard constraints, gates" -v 1
      print ""
      fmt-section "What tools are available?"
      print ""
      fmt-cmd $"($cmd) describe tools" "dev tools, CI tools, just recipes" -v 1
      fmt-cmd $"($cmd) describe tools --actor ci" "just CI-relevant recipes" -v 1
      print ""
      fmt-section "What does this project DO?"
      print ""
      fmt-cmd $"($cmd) describe features" "list all ontology features + Cargo features" -v 1
      fmt-cmd $"($cmd) describe features <id>" "detail: artifacts, deps, edges, dimensions" -v 1
      print ""
      fmt-section "What happens if I change X?"
      print ""
      fmt-cmd $"($cmd) describe impact <node-id>" "trace graph edges, show affected nodes" -v 1
      fmt-cmd $"($cmd) describe impact <node-id> --depth 3" -v 1
      print ""
      fmt-section "Why does X exist?"
      print ""
      fmt-cmd $"($cmd) describe why <id>" "ontology node + ADR + edges" -v 1
      print ""
      fmt-section "Domain extensions"
      print ""
      fmt-cmd $"($cmd) describe extensions" "list .ontology/*.ncl extensions (career, personal, …)" -v 1
      fmt-cmd $"($cmd) describe extensions --dump <stem>" "dump a specific extension (e.g. --dump career)" -v 1
      print ""
      fmt-aliases [
        { short: "d",      long: "describe" },
        { short: "d s",    long: "describe search <term>" },
        { short: "d fi",   long: "describe search <term>  (legacy alias)" },
        { short: "d p",    long: "describe project" },
        { short: "d cap",  long: "describe capabilities" },
        { short: "d con",  long: "describe constraints" },
        { short: "d t",    long: "describe tools" },
        { short: "d tls",  long: "describe tools" },
        { short: "d fea",  long: "describe features" },
        { short: "d f",    long: "describe features" },
        { short: "d i",    long: "describe impact <id>" },
        { short: "d imp",  long: "describe impact <id>" },
        { short: "d w",    long: "describe why <id>" },
        { short: "d ext",  long: "describe extensions" },
      ]
    },
    "search" | "s" => {
      print ""
      fmt-header "SEARCH  (ontology + bookmarks)"
      fmt-sep
      fmt-info "Search ontology nodes, ADRs and modes. Results are interactive (picker)"
      fmt-info "or machine-readable. Bookmarks persist to reflection/search_bookmarks.ncl."
      print ""
      fmt-section "Search"
      print ""
      fmt-cmd $"($cmd) s <term>" "search + interactive selector in TTY, list in pipe/non-TTY" -v 1
      fmt-cmd $"($cmd) s <term> --level Axiom" "filter: Axiom | Tension | Practice | Project" -v 1
      fmt-cmd $"($cmd) s <term> --fmt <fmt>" "output format: text* | json (j) | yaml (y) | toml (t) | md (m)" -v 1
      fmt-cmd $"($cmd) s <term> --clip" "copy output to clipboard — combinable with --fmt" -v 1
      fmt-cmd $"($cmd) describe search <term>" "full form (same command)" -v 1
      print ""
      fmt-info "--fmt and --clip work on any ontoref command, not just search."
      print ""
      fmt-section "Combined search"
      print ""
      fmt-cmd $"($cmd) qs <term>" "QA-first → ontology fallback" -v 1
      fmt-cmd $"($cmd) sq <term>" "ontology-first + QA results appended" -v 1
      print ""
      fmt-section "Bookmarks  (saved to reflection/search_bookmarks.ncl)"
      print ""
      fmt-info "Star any result in the UI to bookmark it — persisted to NCL, git-versioned."
      fmt-info "Bookmarks are shared between CLI and UI (same NCL file)."
      print ""
      fmt-aliases [
        { short: "s",    long: "search <term>" },
        { short: "f",    long: "search <term>  (legacy alias)" },
        { short: "d s",  long: "describe search <term>" },
        { short: "d fi", long: "describe search <term>  (legacy alias)" },
      ]
    },
    "qa" | "q" => {
      print ""
      fmt-header "QA  (questions & answers)"
      fmt-sep
      fmt-info "Curated Q&A pairs persisted to reflection/qa.ncl — git-versioned,"
      fmt-info "MCP-accessible, shared between CLI and UI."
      print ""
      fmt-section "Query"
      print ""
      fmt-cmd $"($cmd) q <term>" "word-overlap search; falls back to ontology if no QA hit" -v 1
      fmt-cmd $"($cmd) q <term> --global" "also search ONTOREF_ROOT global qa.ncl" -v 1
      fmt-cmd $"($cmd) q <term> --no-fallback" "QA only, no ontology fallback" -v 1
      fmt-cmd $"($cmd) q <term> --fmt <fmt>" "output format: text* | json (j) | yaml (y) | toml (t) | md (m)" -v 1
      fmt-cmd $"($cmd) q <term> --clip" "copy output to clipboard — combinable with --fmt" -v 1
      fmt-info "--fmt and --clip work on any ontoref command, not just q."
      fmt-cmd $"($cmd) qs <term>" "QA-first → ontology fallback (shortcut)" -v 1
      print ""
      fmt-section "Add entries"
      print ""
      fmt-cmd $"($cmd) qa add \"<question>\" \"<answer>\"" "add to project qa.ncl (developer+)" -v 1
      fmt-cmd $"($cmd) qa add --global \"<q>\" \"<a>\"" "add to global qa.ncl (admin only)" -v 1
      print ""
      fmt-section "List"
      print ""
      fmt-cmd $"($cmd) qa list" "list project QA entries" -v 1
      fmt-cmd $"($cmd) qa list --global" "list global QA entries" -v 1
      fmt-cmd $"($cmd) qa list --all" "merge project + global" -v 1
      print ""
      fmt-aliases [
        { short: "q",  long: "qa search <term>" },
        { short: "qs", long: "qa search → ontology fallback" },
        { short: "sq", long: "search → qa results appended" },
      ]
    },
    "log" => {
      print ""
      fmt-header "LOG  (action audit trail)"
      fmt-sep
      fmt-info "JSONL log of all onref commands. Config in .ontoref/config.ncl → log."
      print ""
      fmt-section "Query"
      print ""
      fmt-cmd $"($cmd) log" "show all entries" -v 1
      fmt-cmd $"($cmd) log --tail <n>" "last N entries" -v 1
      fmt-cmd $"($cmd) log --latest" "most recent entry" -v 1
      fmt-cmd $"($cmd) log --since <ts>" "entries after ISO timestamp" -v 1
      fmt-cmd $"($cmd) log --until <ts>" "entries before ISO timestamp" -v 1
      fmt-cmd $"($cmd) log --level <lvl>" "filter: write | read | interactive" -v 1
      fmt-cmd $"($cmd) log --actor <a>" "filter: developer | agent | ci" -v 1
      fmt-cmd $"($cmd) log --timestamps" "show timestamps in output" -v 1
      fmt-cmd $"($cmd) log --fmt <fmt>" "fmt: text* | json | jsonl | table" -v 1
      print ""
      fmt-section "Query filter  (-q column:text, multiple AND-combined)"
      print ""
      fmt-cmd $"($cmd) log -q action:describe" "entries where action contains 'describe'" -v 1
      fmt-cmd $"($cmd) log -q action:backlog -q level:write" "backlog mutations only" -v 1
      fmt-cmd $"($cmd) log -q actor:ci --tail 20 -t" "last 20 CI actions with timestamps" -v 1
      print ""
      fmt-section "Follow"
      print ""
      fmt-cmd $"($cmd) log --follow" "tail -f: live output, Ctrl+C to stop" -v 1
      fmt-cmd $"($cmd) log -f -q action:sync" "follow only sync commands" -v 1
      fmt-cmd $"($cmd) log -f -t" "follow with timestamps" -v 1
      print ""
      fmt-section "Record  (for agents, hooks, scripts)"
      print ""
      fmt-cmd $"($cmd) log record <action>" "log an action manually" -v 1
      fmt-cmd $"($cmd) log record <action> --level write" "explicit level" -v 1
      fmt-cmd $"($cmd) log record <action> --author claude --actor agent" "override author/actor" -v 1
      print ""
      fmt-section "Config"
      print ""
      fmt-cmd $"($cmd) log config" "show log config, levels, file stats" -v 1
      print ""
      fmt-section "Columns: ts | author | actor | level | action"
      print ""
    },
    "migrate" => {
      print ""
      fmt-header "MIGRATE  (protocol migrations)"
      fmt-sep
      fmt-info "Progressive, ordered protocol migrations. Applied = check passes. No state file."
      print ""
      fmt-cmd $"($cmd) migrate list" "all migrations with applied/pending status"
      fmt-cmd $"($cmd) migrate pending" "only pending migrations"
      fmt-cmd $"($cmd) migrate show <id>" "instructions for a specific migration"
      print ""
      fmt-aliases [
        { short: "mg",   long: "migrate" },
        { short: "mg l", long: "migrate list" },
        { short: "mg p", long: "migrate pending" },
      ]
    },
    _ => {
      print $"  (ansi red)Unknown group: ($group)(ansi reset)"
      print ""
      fmt-info "Available groups: check | form | mode | adr | register | backlog | config | sync | coder | manifest | describe | log | migrate"
      print ""
    },
  }
}