commands

var ApplyMetadata = config.CommandMetadata{
	Use:   "apply <plan-file | ->",
	Short: "Execute an AI-generated plan to mutate vault notes",
	Long: `Parse a JSON plan file and execute its operations against the vault.

Plans are typically produced by AI agents to make structured changes to your notes:
setting frontmatter keys, creating new notes, or populating generated regions.
Use preview modes to inspect what will change before writing anything to disk.

THE PLAN FILE

  The argument is a path to a JSON file, or "-" to read from stdin.

  Required shape:
    {"version": 1, "description": "...", "operations": [...]}

  Supported operation types:
    frontmatter_set          Set a frontmatter key in one note
    frontmatter_unset        Remove a frontmatter key from one note
    frontmatter_merge        Merge a map of keys into a note's frontmatter
    generated_region_render  Write content into a delimited generated region
    note_create              Create a new note with frontmatter and body

PREVIEW AND EXECUTION MODES

  --dry-run   Parse and simulate without writing. Shows what would change.
  --diff      With --dry-run, display unified diffs of each note mutation.
  --commit    Auto-stage and commit all changes in one git commit after success.
              Without --commit, writes are applied but not committed.

FLAGS

  --vault <path>  Vault root directory (default: ".")
  --json          Machine-readable output: status envelope, per-operation results,
                  and commit SHA when --commit succeeds.

EXAMPLES

  vaultmind apply ./my-plan.json
      Apply the plan. Changes written to disk but not committed.

  vaultmind apply - < ./my-plan.json
      Read plan from stdin (pipe from an AI agent or another command).

  vaultmind apply ./my-plan.json --dry-run
      Simulate the plan without writing anything.

  vaultmind apply ./my-plan.json --dry-run --diff
      Simulate and show unified diffs so you see exactly what each mutation looks like.

  vaultmind apply ./my-plan.json --commit
      Apply, then auto-stage and commit in one step using the plan description.

  vaultmind apply ./my-plan.json --json
      Apply with machine-readable output including per-operation status.`,
	ConfigPrefix: "app.apply",
	FlagOverrides: map[string]string{
		"app.apply.vault":   "vault",
		"app.apply.json":    "json",
		"app.apply.dry_run": "dry-run",
		"app.apply.diff":    "diff",
		"app.apply.commit":  "commit",
	},
}

var ArcCandidatesMetadata = config.CommandMetadata{
	Use:   "candidates",
	Short: "Surface arc-distillation candidate moments from episodes (propose-only)",
	Long: "Scan the vault's episode captures and surface candidate transformation moments " +
		"(authority-grants, manifesto-lens invocations) for arc distillation. PROPOSE-ONLY: it " +
		"never writes arcs — the moments are pointers for you to judge, draft, and approve. See " +
		"principle-how-to-write-arcs for the bar a real arc must clear.",
	ConfigPrefix: "app.arc.candidates",
	FlagOverrides: map[string]string{
		"app.arc.candidates.vault": "vault",
		"app.arc.candidates.json":  "json",
	},
}

var AskMetadata = config.CommandMetadata{
	Use:   "ask <query>",
	Short: "Compound search + context-pack: answer 'what do I know about X?'",
	Long: `Search the vault, pick the top hit, and pack token-budgeted context around it.
One command replaces the manual search → recall → summarize chain.

CHOOSE A RENDERING MODE BY INTENT

  vaultmind ask "spreading activation" --pointers-only
      Menu of relevant ids + titles. Cheapest. Use when you want to see what's
      relevant without reading bodies — then 'note get <id>' the one you want.

  vaultmind ask "spreading activation" --preview
      Menu + one-line snippet under each hit. Use when titles aren't enough
      to know what each note is about. Bridges --pointers-only and default.

  vaultmind ask "spreading activation"
      Default. Full token-budgeted context-pack around the top hit. Use when
      you want bodies in working context (not just to identify the right id).

  vaultmind ask "spreading activation" --explain
      Each hit shows per-lane RRF math (dense / sparse / colbert / fts).
      For investigating ranking decisions, not for answering content questions.

ANTI-PATTERN — AVOID

  vaultmind ask "X" --budget 3000 | tail -20
      Don't double-clip. The budget asks the system to compute 3000 tokens of
      context-pack; the tail then throws most of it away. Pick one shape that
      fits the intent:
        --pointers-only           if you want a menu, no bodies
        --preview                 if you want a menu with body snippets
        --budget=N (no tail)      if you really want N tokens of context

OUTPUT INCLUDES

  Search:    [top-hit confidence: strong|moderate|weak]
  Per-hit:   score, id, title, optional snippet (--preview), optional lanes (--explain)
  Context:   target frontmatter + body, then ranked context items (default mode only)`,
	ConfigPrefix: "app.ask",
	FlagOverrides: map[string]string{
		"app.ask.vault":            "vault",
		"app.ask.json":             "json",
		"app.ask.budget":           "budget",
		"app.ask.max_items":        "max-items",
		"app.ask.search_limit":     "search-limit",
		"app.ask.explain":          "explain",
		"app.ask.pointers_only":    "pointers-only",
		"app.ask.preview":          "preview",
		"app.ask.read":             "read",
		"app.ask.quiet_on_nomatch": "quiet-on-no-match",
	},
}

var CheckMetadata = config.CommandMetadata{
	Use:   "check",
	Short: "Run quality checks",
	Long: `Run comprehensive code quality checks using checkmate.

Includes 23 checks across 6 categories:

  Development Environment (2):
    go-version, tools

  Code Quality (2):
    format, lint

  Architecture Validation (10):
    defaults, commands, constants, task-naming, architecture,
    layering, package-org, config-consumption, output-patterns,
    security-patterns

  Security Scanning (2):
    secrets, sast

  Dependencies (6):
    deps, vuln, outdated, license-source, license-binary, sbom-vulns

  Tests (1):
    test

Use --parallel to run checks within each category concurrently.
Use --fail-fast to stop on the first failure.`,
	ConfigPrefix: "app.check",
	FlagOverrides: map[string]string{
		"app.check.fail_fast": "fail-fast",
		"app.check.verbose":   "verbose",
		"app.check.parallel":  "parallel",
		"app.check.category":  "category",
		"app.check.timing":    "timing",
	},
	Examples: []string{
		"check",
		"check --category=security",
		"check -c security,tests",
		"check --fail-fast",
	},
	SeeAlso: []string{"docs"},
}

var DataviewLintMetadata = config.CommandMetadata{
	Use:   "lint",
	Short: "Scan the vault for broken or duplicate VAULTMIND:GENERATED markers",
	Long: `Validate VAULTMIND:GENERATED markers across every note in the vault.

The command reads all notes and checks each one for two classes of problems:

  malformed_markers   A START marker has no matching END, or vice versa, for
                      the same section key. Typically caused by a partial paste
                      or a hand-edit that removed one half of the pair.

  duplicate_markers   The same section key appears more than once in a single
                      note. Rendering would be ambiguous; the second occurrence
                      is flagged.

  read_error          The file could not be read (permissions, encoding).

Run this before "dataview render" to catch problems early. Run it after
manual edits to confirm the markers are still well-formed.

FLAGS

  --json    Machine-readable output. Emits a JSON envelope whose "data" field
            contains files_checked (int), valid (int), and issues (array).
            Each issue has: path, section_key, rule, message, line.
  --vault   Path to the vault root (default: current directory).

OUTPUT INCLUDES

  Text:  "Checked N files: N valid, N issues" followed by one line per issue
         in the form "[rule] path: message".

  JSON:  { "status": "ok"|"warning", "data": { "files_checked": N,
            "valid": N, "issues": [ { "path": "...", "section_key": "...",
            "rule": "...", "message": "...", "line": N } ] } }

EXAMPLES

  vaultmind dataview lint
      Scan the vault in the current directory; print summary and any issues.

  vaultmind dataview lint --vault /path/to/vault
      Scan a vault at an explicit path.

  vaultmind dataview lint --json
      Emit full JSON envelope; useful for piping into other tools.

  vaultmind dataview lint --json | jq '.data.issues'
      Extract just the issues array for scripted checks.`,
	ConfigPrefix: "app.dataviewlint",
	FlagOverrides: map[string]string{
		"app.dataviewlint.vault": "vault",
		"app.dataviewlint.json":  "json",
	},
}

var DataviewRenderMetadata = config.CommandMetadata{
	Use:   "render <note-id-or-path>",
	Short: "Render a generated region",
	Long: `Replace content between VAULTMIND:GENERATED markers with section template content.

Arguments:
  note-id-or-path   Note ID, title, or file path (resolved via entity resolution)

Markers have the format: <!-- VAULTMIND:GENERATED:{key}:START/END -->
Section templates are loaded from .vaultmind/sections/{type}/{key}.md.
Use --section-key to render a specific section (default: all sections).
Use --force to override checksum mismatch (hand-edited content).`,
	ConfigPrefix: "app.dataviewrender",
	FlagOverrides: map[string]string{
		"app.dataviewrender.vault":       "vault",
		"app.dataviewrender.json":        "json",
		"app.dataviewrender.dry_run":     "dry-run",
		"app.dataviewrender.diff":        "diff",
		"app.dataviewrender.commit":      "commit",
		"app.dataviewrender.force":       "force",
		"app.dataviewrender.section_key": "section-key",
	},
}

var DoctorMetadata = config.CommandMetadata{
	Use:          "doctor",
	Short:        "Vault health summary",
	Long:         "Run diagnostics on the vault index and report issues. By default prints summary counts plus per-link details (can be hundreds of lines on a noisy vault). Use --summary for counts only.",
	ConfigPrefix: "app.doctor",
	FlagOverrides: map[string]string{
		"app.doctor.vault":   "vault",
		"app.doctor.json":    "json",
		"app.doctor.summary": "summary",
	},
}

var ExperimentCompareMetadata = config.CommandMetadata{
	Use:   "compare",
	Short: "Surface where retrieval variants disagree, without needing labeled ground truth",
	Long: `Read recent ask/search/context-pack events that recorded shadow variants and
compute pairwise rank-agreement metrics (Jaccard@K and Kendall's tau) for
each variant pair. Reports per-pair means and event counts, with an optional
per-event breakdown.

This command measures disagreement, not correctness. It answers: "do these
two variants tend to return different results?" without requiring any labeled
target notes. Contrast with "experiment report", which measures absolute
quality and requires labeled targets.

METRICS

  Jaccard@K:   Intersection over union of the top-K result sets from two
               variants (0 = no overlap, 1 = identical top-K). Use K to
               control how deep in the ranking you care about.
  Kendall tau: Rank correlation on items shared by both variants
               (-1 = fully reversed, 0 = uncorrelated, 1 = identical order).
               Undefined when fewer than 2 results are shared.

WHEN TO USE

  Use "experiment compare" when you have two or more retrieval variants
  (e.g., a new ranking model shadowing the primary) and want to measure how
  often they diverge, before investing in labeling ground truth for a full
  quality evaluation via "experiment report".

FLAGS

  --k:          top-K depth for Jaccard and the cap on list length for
                Kendall's tau (int; default 10).
  --per-event:  emit one row per event in addition to aggregates (bool).
  --since:      only include events at or after this RFC3339 timestamp (string).
  --session:    restrict to a single session ID (string).
  --caller:     restrict to a single caller label (string).
  --event-type: restrict to one event type: ask, search, or context_pack
                (string; default: all three).
  --json:       emit JSON instead of a table (bool).

EXAMPLES

  vaultmind experiment compare
      # Compare all variants across all recent events, K=10.

  vaultmind experiment compare --k 5
      # Stricter: only count a result as "in top K" if it is in the top 5.

  vaultmind experiment compare --since 2024-06-01T00:00:00Z
      # Only events on or after a cutoff date.

  vaultmind experiment compare --session abc123 --per-event
      # Restrict to one agent session and emit one row per event.

  vaultmind experiment compare --event-type ask --json
      # Only ask events, machine-readable output for scripting.`,
	ConfigPrefix: "app.experimentcompare",
	FlagOverrides: map[string]string{
		"app.experimentcompare.session":    "session",
		"app.experimentcompare.caller":     "caller",
		"app.experimentcompare.since":      "since",
		"app.experimentcompare.event_type": "event-type",
		"app.experimentcompare.k":          "k",
		"app.experimentcompare.per_event":  "per-event",
		"app.experimentcompare.json":       "json",
	},
}

var ExperimentReportMetadata = config.CommandMetadata{
	Use:   "report",
	Short: "Measure retrieval quality: Hit@K and MRR per variant",
	Long: `Read the local experiment database and compute Hit@K and MRR for each
variant. These are absolute quality metrics that tell you how well a
retrieval variant performs when a labeled target exists.

METRICS

  Hit@K: Fraction of lookups where the target note appeared in the top K
         results (0.0 = never found, 1.0 = always in top K).
  MRR:   Mean Reciprocal Rank — average of 1/rank for each lookup where
         the target was found (rank 1 = 1.0, rank 2 = 0.5, rank 3 = 0.33).

WHEN TO USE

  Use "experiment report" when you want to know whether a variant is actually
  correct — not just whether two variants disagree. It requires events where
  a target note was labeled at retrieval time (e.g., spreading-activation
  lookups where the source note is known). Contrast with "experiment compare",
  which measures variant disagreement and needs no labeled ground truth.

FLAGS

  --experiment: restrict to a named experiment (string; default: all experiments).
  --k:          K value for Hit@K (int; default 10).
  --json:       emit JSON instead of a table (bool).

EXAMPLES

  vaultmind experiment report
      # Hit@K and MRR across all variants and experiments, K=10.

  vaultmind experiment report --k 5
      # Stricter threshold: target must appear in the top 5 to count.

  vaultmind experiment report --experiment spreading-activation-v2
      # Metrics only for the named experiment.

  vaultmind experiment report --experiment spreading-activation-v2 --json
      # Machine-readable output for scripting or logging.`,
	ConfigPrefix: "app.experimentreport",
	FlagOverrides: map[string]string{
		"app.experimentreport.experiment": "experiment",
		"app.experimentreport.json":       "json",
		"app.experimentreport.k":          "k",
	},
}

var ExperimentSummaryMetadata = config.CommandMetadata{
	Use:   "summary",
	Short: "Memory usage overview: top recalled notes, session gap stats",
	Long: `Read the local experiment database and report which notes are recalled most
often, how many unique notes have been retrieved, and the distribution of
time gaps between sessions.

Use this as the weekly readout on whether recall is staying focused or
drifting. A small number of notes dominating the top list may signal
retrieval fixation; many unique notes with long gaps between sessions may
signal low vault engagement.

OUTPUT INCLUDES

  Top-N most-recalled notes (note id, title, recall count).
  Total unique notes retrieved across all sessions.
  Session gap distribution (min, median, max time between sessions).

FLAGS

  --top:  number of top-recalled notes to show (int; default 10).
  --json: emit JSON instead of a table (bool).

EXAMPLES

  vaultmind experiment summary
      # Overview with the top 10 recalled notes and session gap stats.

  vaultmind experiment summary --top 20
      # Widen to the top 20 notes to see if recall coverage is broad.

  vaultmind experiment summary --json
      # Machine-readable output for logging or scripting.`,
	ConfigPrefix: "app.experimentsummary",
	FlagOverrides: map[string]string{
		"app.experimentsummary.json": "json",
		"app.experimentsummary.top":  "top",
	},
}

var ExperimentTraceMetadata = config.CommandMetadata{
	Use:          "trace",
	Short:        "Drill into a specific session or note's retrieval history",
	Long:         "Given --session <id>, reports that session's caller (agent + operator) and every retrieval it performed in order. Given --note <id>, reports every session that retrieved that note with caller attribution. Exactly one of --session or --note must be provided.",
	ConfigPrefix: "app.experimenttrace",
	FlagOverrides: map[string]string{
		"app.experimenttrace.session": "session",
		"app.experimenttrace.note":    "note",
		"app.experimenttrace.json":    "json",
	},
}

var ExportMetadata = config.CommandMetadata{
	Use:   "export",
	Short: "Export experiment data as a sanitized JSONL snapshot",
	Long: `Export the experiment DB (sessions, events, outcomes) as a JSONL
stream that you can share with the VaultMind team. The output is sanitized
according to your configured telemetry tier:

  anonymous  Strips vault paths, query text, and result note_ids/paths.
             Aggregate shape (ranks, scores, counts, timestamps, variant
             names) is preserved.
  full       Preserves everything. Use only if you've explicitly opted
             into Full data sharing on first run.
  off        Refused — the user opted out, so producing a file would
             imply we collected data we shouldn't have.

OUTPUT SHAPE

A JSONL stream — one JSON object per line:

  {"kind":"manifest","tier":"anonymous","exported_at":"...",...}
  {"kind":"session","session_id":"...","started_at":"...","ended_at":"..."}
  {"kind":"event","event_id":"...","event_type":"ask","data":{...}}
  {"kind":"outcome","outcome_id":"...","rank":1,"variant":"primary",...}

EXAMPLES

  vaultmind export
      Stream JSONL to stdout. Pipe to gzip or redirect:
        vaultmind export | gzip > vm-export-$(date +%Y%m%d).jsonl.gz

  vaultmind export --output ./vm-export.jsonl
      Write to a file directly.

  vaultmind export --tier full
      Override the configured tier (requires opt-in record).

PRIVACY

The Anonymous tier's stripping contract is tested in
internal/experiment/export_test.go. If the tests change, the contract
documented in telemetry.go must change too.`,
	ConfigPrefix: "app.export",
	FlagOverrides: map[string]string{
		"app.export.output":  "output",
		"app.export.tier":    "tier",
		"app.export.rollup":  "rollup",
		"app.export.vault":   "vault",
		"app.export.preview": "preview",
	},
}

var FrontmatterFixMetadata = config.CommandMetadata{
	Use:   "fix",
	Short: "Backfill missing `created` frontmatter on domain notes",
	Long: `Walk the vault and identify domain notes missing the ` + "`created`" + ` field.
Surface what's missing and the proposed value; with --apply, write the
addition atomically.

Provenance for ` + "`created`" + `: git first-commit (when the file is tracked) → file
mtime → today's date. The first successful resolution wins.

User-owned fields (title, status, tags, related_ids, etc.) are NEVER
touched by this command — only the missing ` + "`created`" + ` field gets backfilled.

Default is dry-run. Pass --apply to write changes. Output as JSON with --json.

Examples:
  vaultmind frontmatter fix --vault .              # dry-run audit
  vaultmind frontmatter fix --vault . --apply      # backfill missing created
  vaultmind frontmatter fix --vault . --json       # machine-readable audit`,
	ConfigPrefix: "app.frontmatterfix",
	FlagOverrides: map[string]string{
		"app.frontmatterfix.vault": "vault",
		"app.frontmatterfix.json":  "json",
		"app.frontmatterfix.apply": "apply",
	},
}

var FrontmatterMergeMetadata = config.CommandMetadata{
	Use:   "merge <note-id-or-path> --file <yaml-file>",
	Short: "Merge multiple frontmatter fields",
	Long: `Merge key-value pairs from a YAML file into the note's frontmatter.

Arguments:
  note-id-or-path   Note ID, title, or file path (resolved via entity resolution)

Required flags:
  --file   Path to a YAML file containing key-value pairs to merge

The YAML file should contain top-level keys matching frontmatter fields.
Existing keys are overwritten; new keys are added. Use --allow-extra to
merge keys not defined in the type schema. Use --dry-run --diff to preview.`,
	ConfigPrefix: "app.frontmattermerge",
	FlagOverrides: map[string]string{
		"app.frontmattermerge.vault":       "vault",
		"app.frontmattermerge.json":        "json",
		"app.frontmattermerge.dry_run":     "dry-run",
		"app.frontmattermerge.diff":        "diff",
		"app.frontmattermerge.commit":      "commit",
		"app.frontmattermerge.allow_extra": "allow-extra",
		"app.frontmattermerge.file":        "file",
	},
}

var FrontmatterNormalizeMetadata = config.CommandMetadata{
	Use:   "normalize [<file-or-path>] [flags]",
	Short: "Normalize frontmatter on a file (sort keys, fix aliases/tags, dates, snake_case)",
	Long: `Normalize frontmatter formatting on a single vault file.

Applies these transformations to the target file's frontmatter:
  - Sort keys into canonical order
  - Convert scalar aliases and tags fields to lists
  - Normalize all date fields (use --strip-time to truncate to date-only)
  - Convert all keys to snake_case

The optional argument is the path to a note file. When omitted, "." is used as the
target (current directory).

FLAGS

  --vault string      Path to vault root (default ".")
  --dry-run           Preview changes without writing to disk
  --diff              Show a unified diff of the proposed changes
  --commit            Stage and commit the file after applying changes
  --strip-time        Convert all datetime fields to date-only (drop time component)
  --json              Output result in JSON format

EXAMPLES

  vaultmind frontmatter normalize notes/my-note.md --dry-run --diff
      Preview what normalizations would be applied, showing a unified diff.

  vaultmind frontmatter normalize notes/my-note.md
      Apply all normalizations and write the file.

  vaultmind frontmatter normalize notes/my-note.md --strip-time --commit
      Normalize and strip time from dates, then stage and commit the change.

  vaultmind frontmatter normalize notes/my-note.md --json
      Apply normalizations and return structured JSON output.

WHEN TO USE

  Use "frontmatter normalize" to clean up a single file before review or commit.
  For setting or removing individual fields, use "frontmatter set" or "frontmatter unset".
  For bulk key-value updates from a YAML file, use "frontmatter merge".`,
	ConfigPrefix: "app.frontmatternormalize",
	FlagOverrides: map[string]string{
		"app.frontmatternormalize.vault":      "vault",
		"app.frontmatternormalize.json":       "json",
		"app.frontmatternormalize.dry_run":    "dry-run",
		"app.frontmatternormalize.diff":       "diff",
		"app.frontmatternormalize.commit":     "commit",
		"app.frontmatternormalize.strip_time": "strip-time",
	},
}

var FrontmatterSetMetadata = config.CommandMetadata{
	Use:   "set <note-id-or-path> <key> <value>",
	Short: "Set a frontmatter field",
	Long: `Set a single frontmatter key to a value. Validates against the type schema.

Arguments:
  note-id-or-path   Note ID, title, or file path (resolved via entity resolution)
  key               Frontmatter key to set (e.g., "status", "tags")
  value             Value to assign (strings, numbers, JSON arrays like '["a","b"]')

The key is validated against the note's type schema. Use --allow-extra to set
keys not defined in the schema. Use --dry-run --diff to preview the change.`,
	ConfigPrefix: "app.frontmatterset",
	FlagOverrides: map[string]string{
		"app.frontmatterset.vault":       "vault",
		"app.frontmatterset.json":        "json",
		"app.frontmatterset.dry_run":     "dry-run",
		"app.frontmatterset.diff":        "diff",
		"app.frontmatterset.commit":      "commit",
		"app.frontmatterset.allow_extra": "allow-extra",
	},
}

var FrontmatterUnsetMetadata = config.CommandMetadata{
	Use:   "unset <note-id-or-path> <key>",
	Short: "Remove a frontmatter field",
	Long: `Remove a frontmatter key from a note's frontmatter.

Arguments:
  note-id-or-path   Note ID, title, or file path (resolved via entity resolution)
  key               Frontmatter key to remove

Returns an error if the key is required by the note's type schema.
Use --dry-run --diff to preview the change.`,
	ConfigPrefix: "app.frontmatterunset",
	FlagOverrides: map[string]string{
		"app.frontmatterunset.vault":   "vault",
		"app.frontmatterunset.json":    "json",
		"app.frontmatterunset.dry_run": "dry-run",
		"app.frontmatterunset.diff":    "diff",
		"app.frontmatterunset.commit":  "commit",
	},
}

var FrontmatterValidateMetadata = config.CommandMetadata{
	Use:   "validate",
	Short: "Check vault notes for frontmatter rule violations",
	Long: `Scan all domain notes and report frontmatter violations against the type registry.
Catches four rule classes: missing required fields, invalid status values, unknown types, and
broken frontmatter references (explicit_relation edges pointing to non-existent notes).

MODES

  Default (indexed):
    Reads from the vault's SQLite index built by "vaultmind index". Fast.
    Use for routine health checks and CI pipelines. Reports the index hash
    in JSON output so results are traceable to a specific index snapshot.

  --live:
    Reads raw .md files on disk instead of the indexed database.
    Use when the index may be stale or you want to validate before indexing.
    No index hash is reported in this mode.

FLAGS

  --vault PATH   Path to vault root (default: ".")
  --live         Validate raw .md files on disk instead of the indexed database
  --json         Output structured JSON instead of human-readable text

OUTPUT INCLUDES (human-readable)

  "Checked N files: M valid, K issues"
  Per issue: [severity] path: message (rule)

  Severity values:  error (missing required field), warning (unknown type,
                    invalid status, broken reference)
  Rule values:      missing_required_field, unknown_type, invalid_status,
                    broken_reference

OUTPUT INCLUDES (--json)

  status:          "ok" or "warning" (warning when any issues found)
  result:
    files_checked  total notes scanned
    valid          notes with no violations
    issues[]       array of {path, id, severity, rule, message, field, value}
  meta:
    vault_path     vault root used
    index_hash     index snapshot identifier (empty in --live mode)

EXAMPLES

  vaultmind frontmatter validate                      # check indexed database in current vault
  vaultmind frontmatter validate --vault ./my-vault   # check a specific vault (indexed)
  vaultmind frontmatter validate --live               # check raw .md files before indexing
  vaultmind frontmatter validate --json               # machine-readable output for CI`,
	ConfigPrefix: "app.frontmatter",
	FlagOverrides: map[string]string{
		"app.frontmatter.vault": "vault",
		"app.frontmatter.json":  "json",
		"app.frontmatter.live":  "live",
	},
}

var GitStatusMetadata = config.CommandMetadata{
	Use:          "status",
	Short:        "Git repository state for VaultMind policies",
	Long:         "Report git repo state relevant to VaultMind mutation policies: branch, dirty files, merge/rebase status.",
	ConfigPrefix: "app.gitstatus",
	FlagOverrides: map[string]string{
		"app.gitstatus.vault": "vault",
		"app.gitstatus.json":  "json",
	},
}

var HooksInstallMetadata = config.CommandMetadata{
	Use:   "install [project-dir]",
	Short: "Install Claude Code hook scripts into a project",
	Long: `Write VaultMind's Claude Code hook scripts to <project-dir>/.claude/scripts/.
The scripts are embedded in the vaultmind binary; this command
copies them out for use by Claude Code's hook system.

PROJECT-DIR

  Directory of the project to install hooks into. Defaults to the
  current working directory if omitted. The script writes to
  <project-dir>/.claude/scripts/. Creates the directory if missing.

WHAT GETS INSTALLED

  All 8 embedded scripts are written to .claude/scripts/. Four are the
  core hooks --merge wires into your settings; the rest are helpers the
  core scripts source or that you opt into separately.

  Core (wired by --merge):
    load-persona.sh       SessionStart — loads identity context
    vault-recall.sh       UserPromptSubmit — per-turn pointers
    vault-track-read.sh   PreToolUse(Read) — access tracking
    capture-episode.sh    SessionEnd — episode transcript capture

  Helpers (written, not wired by default):
    vault-block-read.sh   parked variant — block-and-redirect on Read
    auto-rag-guard.sh     PreToolUse drift gate (opt-in — see auto-RAG)
    auto-rag-evaluate.sh  scores auto-RAG guard decisions
    shell-strip.sh        shared helper sourced by the auto-RAG scripts

After writing the scripts, this command prints the .claude/settings.json
"hooks" stanza that wires them. Pass --merge to apply it for you instead
of copy-pasting (see WIRING below).

  --vault: point the hooks at a specific vault. The stanza bakes
  VAULTMIND_VAULT=<path> into every command so recall, read-tracking,
  episode capture, and persona loading all target that vault instead of
  the built-in default ($CLAUDE_PROJECT_DIR/vaultmind-identity). Omit it
  to keep the default convention.

WIRING (--merge)

  --merge additively merges the four canonical hook entries straight into
  the project's hook config — no hand-editing. The merge NEVER clobbers:
  a project's own hooks are preserved, our entries are de-duplicated (so
  re-running is a no-op), all other settings and key order are kept, and
  malformed settings error out before any write. Pair with
  "hooks uninstall" to cleanly remove only our entries later.

  --local: merge into .claude/settings.local.json (gitignored, personal)
  instead of .claude/settings.json (committed, team-shared). Choose local
  for a personal persona vault; the default for a capability the whole
  team should get.

  --dry-run: with --merge, print the merged result without writing it —
  use it to preview/diff before applying.

OVERWRITE PROTECTION

  Default: refuses to write any script that already exists. Lists
  the conflicts and exits non-zero so the agent can surface them.

  --force: overwrites existing scripts unconditionally. Use when
  refreshing after a vaultmind binary upgrade (the canonical
  source updates; existing copies become stale).

  --only: comma-separated subset of canonical scripts to install
  (e.g. --only auto-rag-guard.sh,shell-strip.sh,auto-rag-evaluate.sh).
  Consumers who've customized some hooks but want a clean canonical
  install of others — pass --only to scope the install. Unknown
  names rejected at lint time so typos surface explicitly.

  Doctor's hook-drift check (vaultmind doctor) flags when installed
  copies differ from the embedded canonical, so refresh-need is
  surfaced explicitly rather than left to guessing.

EXAMPLES

  vaultmind hooks install                                              # install all 8 into current dir
  vaultmind hooks install ~/dev/myproject                              # install all 8 into a specific project
  vaultmind hooks install --force                                      # refresh after binary upgrade
  vaultmind hooks install --json                                       # machine-readable output
  vaultmind hooks install --only auto-rag-guard.sh,shell-strip.sh      # only the auto-RAG slice (companion-project pattern)
  vaultmind hooks install --vault ./my-knowledge                       # print a stanza wired to a specific vault
  vaultmind hooks install --vault ./my-knowledge --merge --dry-run     # preview the merge without writing
  vaultmind hooks install --vault ./my-knowledge --merge               # write scripts AND wire settings.json
  vaultmind hooks install --vault ./my-knowledge --merge --local       # wire personal settings.local.json instead`,
	ConfigPrefix: "app.hooksinstall",
	FlagOverrides: map[string]string{
		"app.hooksinstall.force":  "force",
		"app.hooksinstall.json":   "json",
		"app.hooksinstall.only":   "only",
		"app.hooksinstall.vault":  "vault",
		"app.hooksinstall.merge":  "merge",
		"app.hooksinstall.local":  "local",
		"app.hooksinstall.dryrun": "dry-run",
	},
}

var HooksUninstallMetadata = config.CommandMetadata{
	Use:   "uninstall [project-dir]",
	Short: "Remove VaultMind's Claude Code hook entries from a project",
	Long: `Strip VaultMind's hook entries from a project's Claude Code hook config.
The inverse of "hooks install --merge": it removes only the entries that
reference VaultMind's canonical scripts, leaving a project's own hooks and
all unrelated settings (permissions, etc.) intact.

PROJECT-DIR

  Directory of the project to clean. Defaults to the current working
  directory if omitted.

WHAT GETS REMOVED

  Any hook entry whose command invokes one of VaultMind's scripts
  (load-persona.sh, vault-recall.sh, vault-track-read.sh,
  capture-episode.sh, and the auto-RAG helpers). An event array left
  empty is dropped, and the "hooks" object is dropped if it becomes
  empty. Entries that merely have a similar name are NOT matched —
  removal is anchored to the exact script path, so a project's own
  hooks are never deleted.

  --local: clean .claude/settings.local.json instead of the default
  .claude/settings.json. Run once per file if you wired into both.

  --remove-scripts: also delete the installed scripts under
  .claude/scripts/. Off by default — uninstall touches only the hook
  config unless you ask for the scripts too.

EXAMPLES

  vaultmind hooks uninstall                            # strip our entries from settings.json
  vaultmind hooks uninstall --local                    # strip from settings.local.json
  vaultmind hooks uninstall --remove-scripts           # also delete .claude/scripts/*.sh
  vaultmind hooks uninstall ~/dev/myproject --json     # machine-readable output`,
	ConfigPrefix: "app.hooksuninstall",
	FlagOverrides: map[string]string{
		"app.hooksuninstall.json":          "json",
		"app.hooksuninstall.local":         "local",
		"app.hooksuninstall.removescripts": "remove-scripts",
	},
}

var IndexMetadata = config.CommandMetadata{
	Use:   "index",
	Short: "Scan and index vault notes into SQLite, with optional embedding",
	Long: `Scan the vault directory and update the SQLite index so search and recall
commands see current note contents. By default only re-parses notes whose
content has changed since the last run (incremental). Use --full to purge and
rebuild the entire index from scratch.

FLAGS

  --vault path        Vault root directory to index (default: current dir).
  --full              Force a complete rebuild; purges the index first and
                      re-parses every note. Shows deleted count explicitly.
  --embed             Compute and store embeddings for all note bodies after
                      indexing. Required for hybrid (semantic+keyword) search.
  --model name        Embedding model to use with --embed.
                      "minilm"  — 384-dimensional, fast, pure-Go build.
                      "bge-m3"  — 1024-dimensional, dense+sparse+ColBERT
                                  (3-in-1), ORT-tagged build only.
                      Empty (default): auto-selects bge-m3 on ORT builds,
                      minilm on pure-Go builds.
  --allow-slow-backend  Allow BGE-M3 on the pure-Go hugot backend. Omit this
                      flag and the command refuses with a warning — BGE-M3 on
                      pure-Go takes hours for a medium vault.
  --json              Machine-readable JSON output (envelope format).

EMBEDDING MODELS

  minilm:   Default on pure-Go builds. Fast. Produces 384-dimensional dense
            vectors only. Sufficient for basic semantic search.

  bge-m3:   Default on ORT-tagged builds ("task build:ort"). Produces
            dense (1024d) + sparse + ColBERT vectors in one pass, enabling
            the full 4-way RRF hybrid used by "ask" and "search". Recommended
            for recall quality. Requires an ORT binary; pure-Go falls back to
            minilm silently unless --allow-slow-backend is passed.

OUTPUT INCLUDES

  Human-readable (default):
    "Indexed N notes (M skipped, A added, U updated, D deleted)"
    "Embedded N notes (M skipped, E errors) [model: <name>]"
    Warning line if any notes produced empty sparse/ColBERT output.

  JSON (--json):
    Envelope with index stats (indexed, added, updated, deleted, errors,
    full_rebuild) and, when --embed, embed stats (embedded, skipped, errors,
    model).

EXAMPLES

  vaultmind index                                           # incremental update
  vaultmind index --full                                    # full rebuild from scratch
  vaultmind index --embed                                   # incremental + compute embeddings
  vaultmind index --embed --model minilm                    # force minilm model explicitly
  vaultmind index --embed --model bge-m3                    # bge-m3 (ORT build required)
  vaultmind index --vault ./my-vault --embed --json         # JSON output for scripting`,
	ConfigPrefix: "app.index",
	FlagOverrides: map[string]string{
		"app.index.vault":              "vault",
		"app.index.json":               "json",
		"app.index.full":               "full",
		"app.index.embed":              "embed",
		"app.index.model":              "model",
		"app.index.allow_slow_backend": "allow-slow-backend",
	},
}

var InitMetadata = config.CommandMetadata{
	Use:   "init [path]",
	Short: "Scaffold a fresh vault — persona-shaped, ready for you and your agent",
	Long: `Create a new VaultMind vault at <path> with the standard persona-shaped
type registry, a vault-level README, and starter notes that demonstrate
the schema. After init, you index, embed, and you're ready.

WHAT YOU GET

  <path>/
    .vaultmind/config.yaml       Type registry — identity, principle, arc,
                                 reference, concept, source, decision
    README.md                    Vault model + workflow
    identity/who-am-i.md         Foundational identity note (placeholder)
    references/current-context.md  Live-edge priority note (placeholder)
    principles/principle-example.md  Template — replace or delete
    arcs/arc-example.md          Template — replace or delete

The placeholder notes have today's date in their frontmatter so the
index reads them cleanly without hand-editing. Replace the bodies with
your agent's real content as your collaboration produces it.

EXAMPLES

  vaultmind init ./my-vault
      Standard scaffold at a relative path.

  vaultmind init "$HOME/.vaultmind/persona"
      A vault outside the project tree — common when the agent's
      memory should persist across multiple repos.

  vaultmind init ./vaultmind-identity --wire-hooks
      Scaffold AND wire Claude Code in one step (see ONE-COMMAND SETUP).

  vaultmind init --print-instructions
      Print the embedded agent-onboarding script and exit. No vault
      created. Use this when an AI agent is helping a new user wire
      vaultmind into their environment — paste the output to the
      agent and it walks the user through preflight, project read,
      greenfield + migration paths, and Claude Code wiring with
      diff-preview.

ONE-COMMAND SETUP (--wire-hooks)

  --wire-hooks does the Claude Code wiring for you right after the
  scaffold: it installs the hook scripts into the current project's
  .claude/scripts/ and merges the four hook entries into
  .claude/settings.json, baked to the new vault via VAULTMIND_VAULT.
  The merge is additive and NEVER clobbers — a project's own hooks are
  preserved, re-runs are no-ops, malformed settings error out before any
  write. (This is the same engine as "vaultmind hooks install --merge".)

    --local     wire .claude/settings.local.json (gitignored, personal)
                instead of the committed settings.json
    --dry-run   preview the settings merge without writing it

  The vault is created at <path>; the hooks are wired into the CURRENT
  directory's .claude/ (your project root). After wiring, index + embed
  so recall has something to retrieve, then restart Claude Code. To undo:
  vaultmind hooks uninstall.

NEXT STEPS

  cd <path>
  vaultmind index --vault .            # build the SQLite index
  vaultmind index --embed --vault .    # compute embeddings (one-time)
  vaultmind ask "who am I" --vault .   # see what the agent would see

  For agent-led setup (interview, project read, migration, hooks),
  run: vaultmind init --print-instructions

THE MODEL

VaultMind treats arcs — transformation notes — as the atomic unit of
persona. Identity is carried by the journey, not by the rules. The
default scaffold gives you placeholder identity + current-context
notes and example templates for principles and arcs; let your real
collaboration produce the rest.`,
	ConfigPrefix: "app.init",
	FlagOverrides: map[string]string{
		"app.init.print_instructions": "print-instructions",
		"app.init.wire_hooks":         "wire-hooks",
		"app.init.local":              "local",
		"app.init.dry_run":            "dry-run",
		"app.init.project_dir":        "project-dir",
	},
}

var LinksInMetadata = config.CommandMetadata{
	Use:   "in <id-or-path>",
	Short: "List notes linking to a note (inbound edges)",
	Long: `Find all notes that reference the given note (inbound edges).

Useful for understanding a note's context and impact: which notes depend on
it, cite it as rationale, or point to it as a concept to explore further.

Each result shows the source note's ID, the edge type, and a confidence label
(high, medium, low) reflecting how strongly the reference was detected.

FLAGS

  --edge-type     Filter to a specific edge type (e.g., "cites"). Omit to show all types.
  --json          Output in machine-readable JSON. Includes target_id and a "links" array
                  with source_id, edge_type, confidence, and resolution status per edge.
  --vault         Path to vault root (default: current directory).

EXAMPLES

  vaultmind links in concept-spreading-activation
      Show all notes that reference spreading-activation, one per line:
      source_id  edge_type  confidence.

  vaultmind links in decision-expand-cache --edge-type cites
      Show only notes that cite this decision as rationale.

  vaultmind links in concept-spreading-activation --json
      Machine-readable output; pipe to jq or an agent tool.`,
	ConfigPrefix: "app.links",
	FlagOverrides: map[string]string{
		"app.links.vault":     "vault",
		"app.links.json":      "json",
		"app.links.edge_type": "edge-type",
	},
}

var LinksNeighborsMetadata = config.CommandMetadata{
	Use:   "neighbors <id-or-path>",
	Short: "Explore a note's graph neighborhood via breadth-first traversal",
	Long: `Explore the notes reachable from the given note within N hops (breadth-first traversal).

Useful for finding related material at increasing degrees of separation: direct
references (depth 1), second-order clusters (depth 2), or broader context.
Results are ordered by distance from the starting note and show the connecting
edge type and confidence for each hop.

CONFIDENCE LABELS

  Edges carry a confidence label (high, medium, low) reflecting how strongly
  a reference was detected. Use --min-confidence to prune weak references
  and focus on the most reliable connections.

FLAGS

  --depth           Maximum hops from the starting note (default: 1). Increase
                    to explore further context.
  --min-confidence  Minimum edge confidence to include: high, medium, or low
                    (default: low, includes all edges). Useful for reducing noise.
  --max-nodes       Cap the number of nodes returned (default: 200). If the cap
                    is reached, output notes "(max reached)" so you know the graph
                    was truncated.
  --json            Output in machine-readable JSON. Includes a "nodes" array with
                    id, distance, and edge_from (edge_type, confidence) per node,
                    plus a "max_nodes_reached" boolean.
  --vault           Path to vault root (default: current directory).

EXAMPLES

  vaultmind links neighbors concept-spreading-activation
      Show all notes within 1 hop (direct references), one per line.

  vaultmind links neighbors concept-spreading-activation --depth 2
      Show second-degree connections — notes that cite notes that cite this one.

  vaultmind links neighbors concept-spreading-activation --depth 2 --min-confidence medium
      Second-degree neighborhood, pruned to medium+ confidence edges (reduces noise).

  vaultmind links neighbors concept-spreading-activation --json
      Machine-readable output; pipe to jq or an agent tool.`,
	ConfigPrefix: "app.linksneighbors",
	FlagOverrides: map[string]string{
		"app.linksneighbors.vault":          "vault",
		"app.linksneighbors.json":           "json",
		"app.linksneighbors.depth":          "depth",
		"app.linksneighbors.min_confidence": "min-confidence",
		"app.linksneighbors.max_nodes":      "max-nodes",
	},
}

var LinksOutMetadata = config.CommandMetadata{
	Use:   "out <id-or-path>",
	Short: "List notes referenced by a note (outbound edges)",
	Long: `Find all notes referenced by the given note (outbound edges).

Shows what a note depends on, cites, or extends — useful for tracing a
note's sources, following its reasoning chain, or finding related material.

Each edge includes its type (e.g., "cites", "extends", "references") and a
confidence label (high, medium, low) reflecting how strongly the reference
was detected.

FLAGS

  --edge-type     Filter to a specific edge type (e.g., "cites"). Omit to show all types.
  --json          Output in machine-readable JSON. Includes source_id and a "links" array
                  with edge_type, confidence, target_id, and resolution status per edge.
  --vault         Path to vault root (default: current directory).

EXAMPLES

  vaultmind links out concept-spreading-activation
      Show all outbound edges from the note, one per line: target  edge_type  confidence.

  vaultmind links out decision-expand-cache --edge-type cites
      Show only edges of type "cites" — the sources this decision depends on.

  vaultmind links out concept-spreading-activation --json
      Machine-readable output; pipe to jq or an agent tool.`,
	ConfigPrefix: "app.links",
	FlagOverrides: map[string]string{
		"app.links.vault":     "vault",
		"app.links.json":      "json",
		"app.links.edge_type": "edge-type",
	},
}

var LintFixLinksMetadata = config.CommandMetadata{
	Use:          "fix-links",
	Short:        "Rewrite wikilinks to Obsidian-compatible format",
	Long:         "Detect [[Title]] wikilinks that won't resolve in Obsidian and rewrite to [[filename|Title]].\nDefault is dry-run (preview). Use --fix to apply changes.",
	ConfigPrefix: "app.lintfixlinks",
	FlagOverrides: map[string]string{
		"app.lintfixlinks.vault": "vault",
		"app.lintfixlinks.json":  "json",
		"app.lintfixlinks.fix":   "fix",
	},
}

var MemoryContextPackMetadata = config.CommandMetadata{
	Use:   "context-pack <id-or-path>",
	Short: "Pack the target note and ranked context items within a token budget",
	Long: `Load a target note, then fill a token budget with its ranked neighbors,
stopping when the budget is exhausted. Designed to produce an agent-ready
payload: the target is always included, followed by context items in
priority order (explicit relations first, then inferred edges).

TOKEN BUDGET

  The budget is a soft limit on tokens. Context items are added one by one
  in ranked order; as soon as adding the next item would exceed the budget,
  it is skipped and the "truncated" field in the output is set to true. The
  target note itself is always included regardless of its size.

  Use --slim to reduce the token footprint of context item frontmatter when
  the budget is tight.

FLAGS

  --budget <tokens>
      Token budget for context assembly. Default: 4096.

  --depth <n>
      BFS traversal depth for finding candidate context items. Default: 1
      (direct neighbors only).

  --max-items <n>
      Maximum number of context items to include. 0 means no limit beyond
      the token budget. Default: 0.

  --slim
      Reduce each context item's frontmatter to {type, title, status} only,
      saving tokens for more items.

  --vault <path>
      Path to vault root. Default: ".".

  --json
      Output as a JSON envelope instead of text.

OUTPUT INCLUDES

  target:        the target note's frontmatter and body
  context:       ranked context items, each with frontmatter (full or slim)
  used_tokens:   tokens consumed
  budget_tokens: the requested budget
  truncated:     true if one or more items were dropped due to budget

EXAMPLES

  vaultmind memory context-pack concept-spreading-activation
      # default 4096-token pack around the target

  vaultmind memory context-pack concept-spreading-activation --budget 2000 --slim
      # tight budget, slim frontmatter to fit more items

  vaultmind memory context-pack concept-spreading-activation --max-items 8 --slim --json
      # cap at 8 items, slim, machine-readable (preferred for agent hooks)

WHEN TO USE

  Use context-pack when an agent needs a self-contained, token-bounded
  working context around a topic. For a full neighborhood traversal without
  a budget, use "memory recall". For a flat list of related notes, use
  "memory related".`,
	ConfigPrefix: "app.memorycontextpack",
	FlagOverrides: map[string]string{
		"app.memorycontextpack.vault":     "vault",
		"app.memorycontextpack.json":      "json",
		"app.memorycontextpack.budget":    "budget",
		"app.memorycontextpack.depth":     "depth",
		"app.memorycontextpack.max_items": "max-items",
		"app.memorycontextpack.slim":      "slim",
	},
}

var MemoryRecallMetadata = config.CommandMetadata{
	Use:   "recall <id-or-path>",
	Short: "Traverse the graph from a note and return neighbors with full frontmatter",
	Long: `Perform a breadth-first traversal starting from a target note and return all
neighbors within the specified depth. Every node in the result carries its
full frontmatter, so callers get a rich, typed neighborhood without follow-up
note-get calls.

BFS (breadth-first search) means depth=1 returns only direct neighbors,
depth=2 includes their neighbors as well, and so on.

CONFIDENCE LEVELS

  Edges in the vault carry a confidence level (low, medium, high).
  --min-confidence sets the floor: only edges at or above that level are
  traversed. The default is "high" so recall stays precise; lower it to
  "medium" or "low" to include weaker, LLM-inferred relationships.

FLAGS

  --depth <n>
      Maximum traversal depth. Default: 1.

  --max-nodes <n>
      Safety limit on result size. Traversal stops when N nodes have been
      collected. The JSON output includes a "max_nodes_reached" field when
      the limit was hit. Default: 50.

  --min-confidence <low|medium|high>
      Minimum edge confidence required to follow an edge. Default: high.

  --vault <path>
      Path to vault root. Default: ".".

  --json
      Output as a JSON envelope instead of text.

EXAMPLES

  vaultmind memory recall concept-spreading-activation
      # direct neighbors (depth 1) at high confidence

  vaultmind memory recall concept-spreading-activation --depth 2 --max-nodes 20
      # up to depth 2, capped at 20 nodes

  vaultmind memory recall concept-spreading-activation --min-confidence medium --json
      # include medium-confidence edges, machine-readable output

WHEN TO USE

  Use recall when you want the full neighborhood around a known note — for
  populating a reasoning window or checking what is explicitly linked.
  For a flat list of edge-typed relations, use "memory related" instead.
  For a token-budgeted payload ready for agent consumption, use
  "memory context-pack" instead.`,
	ConfigPrefix: "app.memoryrecall",
	FlagOverrides: map[string]string{
		"app.memoryrecall.vault":          "vault",
		"app.memoryrecall.json":           "json",
		"app.memoryrecall.depth":          "depth",
		"app.memoryrecall.min_confidence": "min-confidence",
		"app.memoryrecall.max_nodes":      "max-nodes",
	},
}

var MemoryRelatedMetadata = config.CommandMetadata{
	Use:   "related <id-or-path>",
	Short: "List notes related to the target, filtered by edge type",
	Long: `Return all notes directly related to the target, with each result showing
the edge type and confidence level. Use --mode to filter by how the
relationship was established.

MODES

  explicit
      Only edges recorded in the note's frontmatter (related_ids, parent_id,
      source_ids), wikilinks [[...]], and markdown links [...]. These are
      user-curated and carry high confidence.

  inferred
      Only LLM-inferred edges. These represent relationships the model
      detected during indexing but that the user has not explicitly linked.
      They carry medium or low confidence and are useful for discovery.

  mixed
      Both explicit and inferred edges, ranked by confidence and edge type.
      This is the default.

FLAGS

  --mode <explicit|inferred|mixed>
      Which edge types to include. Default: mixed.

  --vault <path>
      Path to vault root. Default: ".".

  --json
      Output as a JSON envelope instead of text.

EXAMPLES

  vaultmind memory related concept-spreading-activation
      # all related notes (explicit + inferred)

  vaultmind memory related concept-spreading-activation --mode explicit
      # only notes with explicit frontmatter or wikilink edges

  vaultmind memory related concept-spreading-activation --mode inferred --json
      # LLM-inferred suggestions only, machine-readable

WHEN TO USE

  Use related for a flat list of directly linked notes when you already know
  the target. For a depth-traversal that follows edges transitively, use
  "memory recall". For a token-budgeted agent payload, use
  "memory context-pack".`,
	ConfigPrefix: "app.memoryrelated",
	FlagOverrides: map[string]string{
		"app.memoryrelated.vault": "vault",
		"app.memoryrelated.json":  "json",
		"app.memoryrelated.mode":  "mode",
	},
}

var MemorySummarizeMetadata = config.CommandMetadata{
	Use:          "summarize [id1 id2 ...]",
	Short:        "Assemble note material for agent synthesis",
	Long:         "Load frontmatter and body excerpts from a set of notes. Agents use this output to create reflection notes. Not an LLM call — data assembly only.",
	ConfigPrefix: "app.memorysummarize",
	FlagOverrides: map[string]string{
		"app.memorysummarize.vault":        "vault",
		"app.memorysummarize.json":         "json",
		"app.memorysummarize.ids":          "ids",
		"app.memorysummarize.include_body": "include-body",
		"app.memorysummarize.max_body_len": "max-body-len",
	},
}

var NoteCreateMetadata = config.CommandMetadata{
	Use:   "create <path> --type <type>",
	Short: "Create a note from a template with field overrides",
	Long: `Create a new note at <path> by expanding the template registered for --type,
then override individual frontmatter fields and body text before writing.

--type is required. The type must be registered in the vault schema; unknown
types are rejected with a list of registered alternatives.

TEMPLATE WORKFLOW

  1. The vault schema maps each type to a template file.
  2. Placeholders in the template (ID, TITLE, PATH, CREATED_DATE) are
     auto-filled from the note path and creation time.
  3. --field key=value patches a frontmatter field after auto-fill (repeatable).
  4. --body or --body-stdin replaces the template body.
  5. Required fields declared by the type must be present and non-empty after
     all substitutions; missing required fields fail with an actionable error
     naming the field and suggesting --field.
  6. The note is written to <vault-root>/<path>. The path must stay inside
     the vault directory (path traversal is rejected).

FLAGS

  --type <type>       Note type (required). Must match a type in the vault schema.
  --vault <dir>       Path to vault root (default: ".").
  --field key=value   Patch a frontmatter field after template expansion (repeatable).
  --body <text>       Replace the template body with literal text.
  --body-stdin        Read the body replacement from stdin (overrides --body).
  --commit            Stage and git-commit the new file after writing.
  --json              Output a structured envelope instead of the default one-liner.

OUTPUT INCLUDES (--json)

  path        vault-relative path of the created note
  id          auto-assigned note ID
  type        the --type value used
  created     true on success
  write_hash  sha256 of the file as written (integrity check)
  commit_sha  git commit SHA when --commit is used (omitted otherwise)
  warnings    list of non-fatal issues (e.g. re-index failure)

EXAMPLES

  vaultmind note create concepts/memory.md --type concept --vault my-vault
      # create a concept note; auto-fill ID, TITLE, CREATED_DATE from the template

  vaultmind note create principles/focus.md --type principle --field author=alice
      # create and set the "author" frontmatter field in one step

  vaultmind note create episodes/ep-001.md --type episode --body-stdin --vault vaultmind-identity <<EOF
  Session opened. Explored spreading-activation scoring.
  EOF
      # pipe a multi-line body from stdin

  vaultmind note create arcs/growth.md --type arc --commit --vault vaultmind-identity
      # create and immediately git-commit the new file`,
	ConfigPrefix: "app.notecreate",
	FlagOverrides: map[string]string{
		"app.notecreate.vault":  "vault",
		"app.notecreate.json":   "json",
		"app.notecreate.type":   "type",
		"app.notecreate.body":   "body",
		"app.notecreate.commit": "commit",
	},
}

var NoteGetMetadata = config.CommandMetadata{
	Use:   "get <id-or-path>",
	Short: "Get a note's full content and metadata",
	Long: `Return full note content including frontmatter, body, headings, and blocks.
Use --frontmatter-only to omit body text.

This is the canonical READ-ONE-NOTE-BY-ID path. It fires access tracking
(reinforcement signal for the activation-based ranking layer), so prefer it
over the Read tool when you want to read a vault note's body. The cleanest
read path is also the tracked one.

EXAMPLES

  vaultmind note get reference-current-context --vault vaultmind-identity
      Print the note's id+type+title header followed by the body inline.

  vaultmind note get reference-current-context --vault vaultmind-identity --json
      Same content, structured envelope. Use from scripts.

  vaultmind note get concept-act-r --vault vaultmind-vault --frontmatter-only
      Header + frontmatter only, no body. Use to inspect tags/related_ids.

PAIRS WELL WITH

  vaultmind ask "X" --pointers-only      # find the right id, then note get it
  vaultmind self                          # see what you've been touching`,
	ConfigPrefix: "app.note",
	FlagOverrides: map[string]string{
		"app.note.vault":            "vault",
		"app.note.json":             "json",
		"app.note.frontmatter_only": "frontmatter-only",
	},
}

var PingMetadata = config.CommandMetadata{
	Use:   "ping",
	Short: "Responds with a pong",
	Long: `The ping command demonstrates configuration, logging, and optional Bubble Tea UI.
- Without arguments, prints "Pong".
- Supports overriding its output and an optional interactive UI.`,
	ConfigPrefix: "app.ping",
	FlagOverrides: map[string]string{
		"app.ping.output_message": "message",
		"app.ping.output_color":   "color",
		"app.ping.ui":             "ui",
	},
	Examples: []string{
		"ping",
		"ping --message 'Hello World!'",
		"ping --color green",
		"ping --ui",
	},
	SeeAlso: []string{"docs"},
}

var ResolveMetadata = config.CommandMetadata{
	Use:   "resolve <id-or-title-or-alias>",
	Short: "Resolve ambiguous note references to canonical IDs",
	Long: `Turn a fragment — a partial ID, a title, an alias, or a file path — into
one or more matched notes with a resolution tier that explains how the match
was found.

Use resolve when you have a string that might refer to a note but you are not
certain of its exact ID, or when you want to check whether a reference is
ambiguous before acting on it.

RESOLUTION TIERS

  Resolve walks the input through five tiers, returning at the first hit:

    path      Input contains "/" or ends in ".md"; matched against stored paths.
    id        Exact match against the note's canonical ID.
    title     Exact match against the note's title field.
    alias     Exact match against any alias stored for the note.
    normalized  Case-insensitive match on title or alias, including
                treating hyphens and underscores as spaces.

  If no tier produces a hit, resolve reports "No match".
  If a tier produces multiple hits, the result is marked ambiguous and all
  candidates are returned — resolve does not silently pick one.

FLAGS

  --vault: path to the vault root directory (string, default ".")
  --json:  output the full resolution envelope as JSON instead of plain text
           (bool, default false)

OUTPUT INCLUDES

  Plain text (one line per match):
    <id>  <type>  <title>  (<path>)

  JSON envelope:
    resolved          whether any match was found
    ambiguous         true when multiple notes matched at the same tier
    input             the original query string
    resolution_tier   which tier produced the match ("id", "title", etc.)
    matches[]         array of { id, type, title, path, status }

WHEN TO USE

  resolve   You have a fragment or alias and need the canonical ID.
            Handles ambiguity explicitly — tells you when a string is not unique.
  ask       You have a semantic question and want ranked context around the
            best-matching note; works across whole vault topics, not single IDs.
  search    You want a ranked list of notes matching a free-text query without
            needing exact disambiguation.

EXAMPLES

  vaultmind resolve concept-act-r --vault ./my-vault         # exact ID lookup
  vaultmind resolve "ACT-R" --vault ./my-vault               # case-insensitive title match
  vaultmind resolve act-r --vault ./my-vault                 # normalized (hyphen → space)
  vaultmind resolve notes/decision-foo.md --vault .          # path shortcut
  vaultmind resolve spreading-activation --json --vault .    # machine-readable output`,
	ConfigPrefix: "app.resolve",
	FlagOverrides: map[string]string{
		"app.resolve.vault": "vault",
		"app.resolve.json":  "json",
	},
}

var SchemaListTypesMetadata = config.CommandMetadata{
	Use:   "list-types",
	Short: "Show the vault's type registry — available note types, required fields, and valid statuses",
	Long: `Return every registered note type together with its required-fields flag and allowed status values.

Agents run this during startup or before creating notes to discover what types the vault
supports and what constraints apply to each. Humans rarely need it directly; its primary
use is feeding agent initialization logic and type-aware tooling.

OUTPUT INCLUDES

  Text (default):  one line per type — name (12-char padded), required=true|false, statuses=[...]
  JSON (--json):   envelope with status "ok", command "schema list-types", and a "data"
                   object keyed by type name; each value carries required and statuses fields.

FLAGS

  --json    Output the registry as a JSON envelope (default: human-readable text).
  --vault   Path to vault root (default: current directory).

EXAMPLES

  vaultmind schema list-types
      Print the type registry as a text table — use to see at a glance what types exist.

  vaultmind schema list-types --vault ./my-vault
      Same, but targeting a vault at a specific path.

  vaultmind schema list-types --json
      Return the registry as a JSON envelope; use in agent init scripts or tooling
      that needs to validate a type before calling "note create".

WHEN TO USE

  Run list-types before creating a note when you are unsure whether a type name is valid
  or which status values are accepted. It is cheaper than attempting a write and handling
  a validation error.`,
	ConfigPrefix: "app.schema",
	FlagOverrides: map[string]string{
		"app.schema.vault": "vault",
		"app.schema.json":  "json",
	},
}

var SearchMetadata = config.CommandMetadata{
	Use:   "search <query>",
	Short: "Search vault notes by keyword, semantic similarity, or both",
	Long: `Search note titles and body text and return ranked hits.
Keyword mode is the default and needs no index; semantic and hybrid modes
require embeddings built with "vaultmind index --embed".

SEARCH MODES

  keyword (default)  Pure full-text search using SQLite FTS5. Fast, no
                     embeddings needed. Best for exact-term queries.

  semantic           Embedding-based similarity search. Needs: vaultmind index --embed.
                     Best for concept queries where exact wording varies.

  hybrid             Combines keyword and semantic via reciprocal rank fusion (RRF).
                     Best all-around mode when embeddings are available.
                     Needs: vaultmind index --embed.

FLAGS

  --vault string    Path to vault root (default ".")
  --mode string     Search mode: keyword, semantic, or hybrid (default "keyword")
  --type string     Filter results to notes of this type (e.g. concept, source)
  --tag string      Filter results to notes with this tag
  --limit int       Maximum number of results to return (default 20)
  --offset int      Skip the first N results for pagination (default 0)
  --json            Output results as a JSON envelope instead of plain text

OUTPUT INCLUDES

  Default:  one line per hit — id followed by title
  --json:   envelope with query, offset, limit, total, and hits array
            (each hit: id, title, score, type, path)

WHEN TO USE

  search:  You want to browse ranked hits and choose what to read next.
  ask:     You want the top hit plus token-budgeted context already packed —
           one command replaces the search-then-recall chain.

EXAMPLES

  vaultmind search "spreading activation" --vault my-vault
  vaultmind search "memory consolidation" --mode hybrid --vault my-vault       # semantic + keyword
  vaultmind search "attention" --type concept --tag learning --vault my-vault  # filtered
  vaultmind search "retrieval" --limit 5 --json --vault my-vault               # machine-readable top 5
  vaultmind search "recall" --limit 10 --offset 10 --vault my-vault            # page 2`,
	ConfigPrefix: "app.search",
	FlagOverrides: map[string]string{
		"app.search.vault":  "vault",
		"app.search.json":   "json",
		"app.search.limit":  "limit",
		"app.search.offset": "offset",
		"app.search.type":   "type",
		"app.search.tag":    "tag",
		"app.search.mode":   "mode",
	},
}

var SelfMetadata = config.CommandMetadata{
	Use:   "self",
	Short: "Show your memory state — recent, hot, stale notes",
	Long: `Render the activation state of your vault — first-person AX for the agent
using vaultmind as long-term memory. Reads access_count + last_accessed_at,
which RecordNoteAccess populates on every successful Ask + note get.

THREE SECTIONS

  Recent (newest first):     The last N notes you touched. Anchors you in
                             "where am I right now" in conceptual space.
  Hot (top activation):      Ranked by ln(1+count) - d*ln(elapsed_hours).
                             Captures both frequency and recency.
  Stale (drifting away):     Accessed but past the threshold. What your
                             memory used to hold but isn't returning to.

The hot column shows activation as +0.00 for the leader, then negative
numbers indicating how-much-below the leader. Order-preserving — the
sign is just relative-distance, not "broken".

EXAMPLES

  vaultmind self --vault vaultmind-vault
      Default — limit 10 per section, 7-day stale threshold.

  vaultmind self --vault vaultmind-identity --limit 5
      Tighter view — 5 rows per section.

THIS IS ALREADY AUTO-INJECTED

  The SessionStart hook runs 'vaultmind self' for both identity and research
  vaults at session start. You see your memory state ambiently before any
  work begins. Run this command manually only when you want a fresh check
  mid-session.`,
	ConfigPrefix: "app.self",
	FlagOverrides: map[string]string{
		"app.self.vault": "vault",
		"app.self.limit": "limit",
	},
}

var VaultStatusMetadata = config.CommandMetadata{
	Use:          "status",
	Short:        "Vault status summary (cold-start)",
	Long:         "Single-call summary combining note counts, type registry, index freshness, and validation issues.",
	ConfigPrefix: "app.vaultstatus",
	FlagOverrides: map[string]string{
		"app.vaultstatus.vault": "vault",
		"app.vaultstatus.json":  "json",
	},
}