# cli/commands.yaml
# Philosophy: one canonical spec stops drift between docs & code.
link:
  description: "Manage typed relationships between files"
  actions:
    add:
      args: [from, to]
      flags: ["--type"]
    rm:
      args: [from, to]
      flags: ["--type"]
    list:
      args: [pattern]
      flags: ["--direction", "--type"]
    backlinks:
      args: [pattern]

coll:
  description: "Manage named collections of files"
  actions:
    create:
      args: [name]
    add:
      args: [name, file_pattern]
    list:
      args: [name]

view:
  description: "Save and use smart views (saved queries)"
  actions:
    save:
      args: [view_name, query]
    list: {}
    exec:
      args: [view_name]

state:
  description: "Track workflow states on files"
  actions:
    set:
      args: [file_pattern, new_state]
    transitions-add:
      args: [from_state, to_state]
    log:
      args: [file_pattern]

task:
  description: "Extract TODOs and manage tasks"
  actions:
    scan:
      args: [directory]
    list:
      flags: ["--due-today"]

remind:
  description: "Attach reminders to files"
  actions:
    set:
      args: [file_pattern, timestamp, message]

annotate:
  description: "Add notes or highlights to files"
  actions:
    add:
      args: [file, note]
      flags: ["--range", "--highlight"]
    list:
      args: [file_pattern]

version:
  description: "Versioning and diffs"
  actions:
    diff:
      args: [file]

event:
  description: "Link files to dates/events"
  actions:
    add:
      args: [file, date, description]
    timeline: {}

backup:
  description: "Create, prune or verify backups"
  actions:
    run:
      flags: ["--dir", "--prune", "--verify", "--file"]
