na 1.2.87 → 1.2.88

data/lib/na/plugins.rb

@@ -0,0 +1,419 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'csv'
+
+module NA
+  # Plugins module for NA
+  module Plugins
+    module_function
+
+    def plugins_home
+      File.expand_path('~/.local/share/na/plugins')
+    end
+
+    def ensure_plugins_home
+      dir = plugins_home
+      return if File.directory?(dir)
+
+      FileUtils.mkdir_p(dir)
+      readme = File.join(dir, 'README.md')
+      File.write(readme, default_readme_contents) unless File.exist?(readme)
+      create_sample_plugins(dir)
+    end
+
+    def list_plugins
+      dir = plugins_home
+      return {} unless File.directory?(dir)
+
+      Dir.children(dir).each_with_object({}) do |entry, acc|
+        path = File.join(dir, entry)
+        next unless File.file?(path)
+        next if entry =~ /\.(md|bak)$/i
+        next unless shebang?(path)
+
+        base = File.basename(entry, File.extname(entry))
+        key = base.gsub(/[\s_]/, '')
+        acc[key.downcase] = path
+      end
+    end
+
+    def resolve_plugin(name)
+      return nil unless name && !name.to_s.strip.empty?
+
+      normalized = name.to_s.strip.gsub(/[\s_]/, '').downcase
+      candidates = list_plugins
+      return candidates[normalized] if candidates.key?(normalized)
+
+      # Fallback: try exact filename match in dir
+      path = File.join(plugins_home, name)
+      File.file?(path) ? path : nil
+    end
+
+    def shebang_for(file)
+      first = begin
+        File.open(file, 'r', &:readline)
+      rescue StandardError
+        ''
+      end
+      first.start_with?('#!') ? first.sub('#!', '').strip : nil
+    end
+
+    def parse_plugin_metadata(file)
+      meta = { 'input' => nil, 'output' => nil, 'name' => nil }
+      lines = File.readlines(file, chomp: true)
+      return meta if lines.empty?
+
+      # skip shebang
+      i = 0
+      i += 1 if lines[0].to_s.start_with?('#!')
+      # skip leading blanks
+      i += 1 while i < lines.length && lines[i].strip.empty?
+      while i < lines.length
+        line = lines[i]
+        break if line.strip.empty?
+
+        # strip common comment leaders
+        stripped = line.sub(%r{^\s*(#|//)}, '').strip
+        if (m = stripped.match(/^([A-Za-z]+)\s*:\s*(.+)$/))
+          key = m[1].downcase
+          val = m[2].strip
+          case key
+          when 'input', 'output'
+            meta[key] = val.downcase
+          when 'name', 'title'
+            meta['name'] = val
+          end
+        end
+        break if meta.values_at('input', 'output', 'name').compact.size == 3
+
+        i += 1
+      end
+      meta
+    end
+
+    def run_plugin(file, stdin_str)
+      interp = shebang_for(file)
+      cmd = interp ? %(#{interp} #{Shellwords.escape(file)}) : %(sh #{Shellwords.escape(file)})
+      IO.popen(cmd, 'r+', err: %i[child out]) do |io|
+        io.write(stdin_str.to_s)
+        io.close_write
+        io.read
+      end
+    end
+
+    def serialize_actions(actions, format: 'json', divider: '||')
+      case format.to_s.downcase
+      when 'json'
+        JSON.pretty_generate(actions)
+      when 'yaml', 'yml'
+        YAML.dump(actions)
+      when 'csv'
+        CSV.generate(force_quotes: true) do |csv|
+          csv << %w[action arguments file_path line parents text note tags]
+          actions.each do |a|
+            csv << [
+              (a['action'] && a['action']['action']) || 'UPDATE',
+              Array(a['action'] && a['action']['arguments']).join(','),
+              a['file_path'],
+              a['line'],
+              Array(a['parents']).join('>'),
+              a['text'] || '',
+              a['note'] || '',
+              serialize_tags(a['tags'])
+            ]
+          end
+        end
+      when 'text', 'txt'
+        actions.map { |a| serialize_text(a, divider: divider) }.join("\n")
+      else
+        JSON.generate(actions)
+      end
+    end
+
+    def parse_actions(str, format: 'json', divider: '||')
+      case format.to_s.downcase
+      when 'json'
+        JSON.parse(str)
+      when 'yaml', 'yml'
+        YAML.safe_load(str, permitted_classes: [Time], aliases: true)
+      when 'csv'
+        rows = CSV.parse(str.to_s, headers: true)
+        rows = CSV.parse(str.to_s) if rows.nil? || rows.empty?
+        rows.map do |row|
+          r = if row.is_a?(CSV::Row)
+                row.to_h
+              else
+                {
+                  'action' => row[0], 'arguments' => row[1], 'file_path' => row[2], 'line' => row[3],
+                  'parents' => row[4], 'text' => row[5], 'note' => row[6], 'tags' => row[7]
+                }
+              end
+          {
+            'file_path' => r['file_path'].to_s,
+            'line' => r['line'].to_i,
+            'parents' => (r['parents'].to_s.empty? ? [] : r['parents'].split('>').map(&:strip)),
+            'text' => r['text'].to_s,
+            'note' => r['note'].to_s,
+            'tags' => parse_tags(r['tags']),
+            'action' => normalize_action_block(r['action'], r['arguments'])
+          }
+        end
+      when 'text', 'txt'
+        str.to_s.split(/\r?\n/).reject(&:empty?).map { |line| parse_text(line, divider: divider) }
+      end
+    end
+
+    def serialize_text(action, divider: '||')
+      parts = []
+      act = action['action'] && action['action']['action']
+      args = Array(action['action'] && action['action']['arguments']).join(',')
+      parts << (act || 'UPDATE')
+      parts << args
+      parts << "#{action['file_path']}:#{action['line']}"
+      parts << Array(action['parents']).join('>')
+      parts << (action['text'] || '')
+      parts << (action['note'] || '').gsub("\n", '\\n')
+      parts << serialize_tags(action['tags'])
+      parts.join(divider)
+    end
+
+    def parse_text(line, divider: '||')
+      tokens = line.split(divider, 7)
+      action_token = tokens[0].to_s.strip
+      if action_name?(action_token)
+        act = action_token
+        args = tokens[1]
+        fileline = tokens[2]
+        parents = tokens[3]
+        text = tokens[4]
+        note = tokens[5]
+        tags = tokens[6]
+      else
+        act = 'UPDATE'
+        args = ''
+        fileline = tokens[0]
+        parents = tokens[1]
+        text = tokens[2]
+        note = tokens[3]
+        tags = tokens[4]
+      end
+      fp, ln = (fileline || '').split(':', 2)
+      {
+        'file_path' => fp.to_s,
+        'line' => ln.to_i,
+        'parents' => (parents.to_s.empty? ? [] : parents.split('>').map(&:strip)),
+        'text' => text.to_s,
+        'note' => note.to_s.gsub('\\n', "\n"),
+        'tags' => parse_tags(tags),
+        'action' => normalize_action_block(act, args)
+      }
+    end
+
+    def serialize_tags(tags)
+      Array(tags).map { |t| t['value'].to_s.empty? ? t['name'].to_s : %(#{t['name']}(#{t['value']})) }.join(';')
+    end
+
+    def parse_tags(str)
+      return [] if str.to_s.strip.empty?
+
+      str.split(';').map do |part|
+        if (m = part.match(/^([^()]+)\((.*)\)$/))
+          { 'name' => m[1].strip, 'value' => m[2].to_s }
+        else
+          { 'name' => part.strip, 'value' => '' }
+        end
+      end
+    end
+
+    def shebang?(file)
+      first = begin
+        File.open(file, 'r', &:readline)
+      rescue StandardError
+        ''
+      end
+      first.start_with?('#!')
+    end
+
+    def action_name?(name)
+      return false if name.to_s.strip.empty?
+
+      %w[update delete complete finish restore unfinish archive add_tag delete_tag remove_tag move].include?(name.to_s.downcase)
+    end
+
+    def normalize_action_block(action_name, args)
+      name = (action_name || 'UPDATE').to_s.upcase
+      name = 'DELETE_TAG' if name == 'REMOVE_TAG'
+      name = 'COMPLETE' if name == 'FINISH'
+      name = 'RESTORE' if name == 'UNFINISH'
+      {
+        'action' => name,
+        'arguments' => args.is_a?(Array) ? args : args.to_s.split(/[,;]/).map(&:strip).reject(&:empty?)
+      }
+    end
+
+    def default_readme_contents
+      <<~MD
+        # NA Plugins
+
+        Put your scripts in this folder. Each plugin must start with a shebang (#!) so NA knows how to execute it.
+
+        - Plugins receive input on STDIN and must write output to STDOUT
+        - Do not modify the original files; NA applies changes based on your output
+        - Do not change `file_path` or `line` in your output
+        - You may change `parents` (to move), `text`, `note`, and `tags`
+
+        ## Metadata (optional)
+        Add a comment block (after the shebang) with key: value pairs to declare defaults. Keys are case-insensitive.
+
+        ```
+        # input: json
+        # output: json
+        # name: My Fancy Plugin
+        ```
+
+        CLI flags `--input/--output/--divider` override metadata when provided.
+
+        ## Formats
+        Valid input/output formats: `json`, `yaml`, `csv`, `text`.
+
+        Text format line:
+        ```
+        ACTION||ARGS||file_path:line||parents||text||note||tags
+        ```
+        - If the first token isn’t a known ACTION, it’s treated as `file_path:line` and ACTION defaults to `UPDATE`.
+        - `parents`: `Parent>Child>Leaf`
+        - `tags`: `name(value);name;other(value)`
+
+        JSON/YAML object schema per action:
+        ```json
+        {
+          "action": { "action": "UPDATE", "arguments": ["arg1"] },
+          "file_path": "/path/to/todo.taskpaper",
+          "line": 15,
+          "parents": ["Project", "Subproject"],
+          "text": "- Do something @tag(value)",
+          "note": "Notes can\nspan lines",
+          "tags": [ { "name": "tag", "value": "value" } ]
+        }
+        ```
+
+        ACTION values (case-insensitive): `UPDATE` (default), `DELETE`, `COMPLETE`/`FINISH`, `RESTORE`/`UNFINISH`, `ARCHIVE`, `ADD_TAG`, `DELETE_TAG`/`REMOVE_TAG`, `MOVE`.
+        - For `ADD_TAG`, `DELETE_TAG`/`REMOVE_TAG`, and `MOVE`, provide arguments (e.g., tags or target project).
+
+        ## Examples
+
+        JSON input example (2 actions):
+        ```json
+        [
+          {
+            "file_path": "/projects/todo.taskpaper",
+            "line": 21,
+            "parents": ["Inbox"],
+            "text": "- Example action",
+            "note": "",
+            "tags": []
+          },
+          {
+            "file_path": "/projects/todo.taskpaper",
+            "line": 42,
+            "parents": ["Work", "Feature"],
+            "text": "- Add feature @na",
+            "note": "Spec TKT-123",
+            "tags": [{"name":"na","value":""}]
+          }
+        ]
+        ```
+
+        Text input example (2 actions):
+        ```
+        UPDATE||||/projects/todo.taskpaper:21||Inbox||- Example action||||
+        MOVE||Work:NewFeature||/projects/todo.taskpaper:42||Work>Feature||- Add feature @na||Spec TKT-123||na
+        ```
+
+        A plugin would read from STDIN, transform, and write the same shape to STDOUT. For example, a shell plugin that adds `@bar`:
+        ```bash
+        #!/usr/bin/env bash
+        # input: text
+        # output: text
+        while IFS= read -r line; do
+          [[ -z "$line" ]] && continue
+          IFS='||' read -r a1 a2 a3 a4 a5 a6 a7 <<<"$line"
+          # If first token is not an action, treat it as file:line
+          case "${a1^^}" in
+            UPDATE|DELETE|COMPLETE|FINISH|RESTORE|UNFINISH|ARCHIVE|ADD_TAG|DELETE_TAG|REMOVE_TAG|MOVE) : ;;
+            *) a7="$a6"; a6="$a5"; a5="$a4"; a4="$a3"; a3="$a2"; a2=""; a1="UPDATE";;
+          esac
+          tags="$a7"; tags=${tags:+"$tags;bar"}; tags=${tags:-bar}
+          echo "$a1||$a2||$a3||$a4||$a5||$a6||$tags"
+        done
+        ```
+
+        Python example (JSON):
+        ```python
+        #!/usr/bin/env python3
+        # input: json
+        # output: json
+        import sys, json, time
+        data = json.load(sys.stdin)
+        for a in data:
+            act = a.get('action') or {'action':'UPDATE','arguments':[]}
+            a['action'] = act
+            tags = a.get('tags', [])
+            tags.append({'name':'foo','value':time.strftime('%Y-%m-%d %H:%M:%S')})
+            a['tags'] = tags
+        json.dump(data, sys.stdout)
+        ```
+
+        Tips:
+        - Always preserve `file_path` and `line`
+        - Return only actions you want changed; others can be omitted
+        - For text IO, the field divider defaults to `||` and can be overridden with `--divider`
+      MD
+    end
+
+    def create_sample_plugins(dir)
+      py = File.join(dir, 'Add Foo.py')
+      sh = File.join(dir, 'Add Bar.sh')
+      unless File.exist?(py)
+        File.write(py, <<~PY)
+          #!/usr/bin/env python3
+          # name: Add Foo
+          # input: json
+          # output: json
+          import sys, json, time
+          data = json.load(sys.stdin)
+          now = time.strftime('%Y-%m-%d %H:%M:%S')
+          for a in data:
+              tags = a.get('tags', [])
+              tags.append({'name':'foo','value':now})
+              a['tags'] = tags
+          json.dump(data, sys.stdout)
+        PY
+      end
+      return if File.exist?(sh)
+
+      File.write(sh, <<~SH)
+        #!/usr/bin/env bash
+        # name: Add Bar
+        # input: text
+        # output: text
+        while IFS= read -r line; do
+          if [[ -z "$line" ]]; then continue; fi
+          if [[ "$line" == *"||"* ]]; then
+            fileline=${line%%||*}
+            rest=${line#*||}
+            parents=${rest%%||*}; rest=${rest#*||}
+            text=${rest%%||*}; rest=${rest#*||}
+            note=${rest%%||*}; tags=${rest#*||}
+            if [[ -z "$tags" ]]; then tags="bar"; else tags="$tags;bar"; fi
+            echo "$fileline||$parents||$text||$note||$tags"
+          else
+            echo "$line"
+          fi
+        done
+      SH
+    end
+  end
+end

data/lib/na/string.rb

@@ -193,18 +193,20 @@ class ::String
 
     output = []
     line = []
-    length = 0
+    # Track visible length of current line (exclude the separating space before first word)
+    length = -1
     text = gsub(/(@\S+)\((.*?)\)/) { "#{Regexp.last_match(1)}(#{Regexp.last_match(2).gsub(/ /, '†')})" }
 
     text.split.each do |word|
       uncolored = NA::Color.uncolor(word)
-      if (length + uncolored.length + 1) <= width
+      candidate = length + 1 + uncolored.length
+      if candidate <= width
         line << word
-        length += uncolored.length + 1
+        length = candidate
       else
         output << line.join(' ')
         line = [word]
-        length = uncolored.length + 1
+        length = uncolored.length
       end
     end
     output << line.join(' ')

data/lib/na/version.rb

@@ -5,5 +5,5 @@
 module Na
   ##
   # Current version of the na gem.
-  VERSION = '1.2.87'
+  VERSION = '1.2.88'
 end

data/lib/na.rb

@@ -35,3 +35,4 @@ require 'na/types'
 require 'na/editor'
 require 'na/next_action'
 require 'na/prompt'
+require 'na/plugins'

data/na/Test.todo.markdown

@@ -0,0 +1,32 @@
+---
+comment: 2023-09-03
+keywords: 
+---
+
+Project3:
+Project0:
+	- This is another task @na
+	- How about this one? @na
+	Subproject:
+		- Bollocks @na
+		Subsub:
+			- Hey, I think it's all working @na
+			- Is this at the end? @na
+	- This better work @na
+2023-09-08:
+	Project2:
+		- new_task @na
+		- new_task @na
+		- test task @na
+	Project0:
+		- other task @na
+		- other task @na
+		- There, that's better @na
+		Subproject:
+			- new_task 2 @na
+			- new_task @na
+			- new_task 2 @na
+	Project1:
+		- Test4
+		- Test5
+		- Test6

data/na/test.md

@@ -0,0 +1,21 @@
+---
+comment: 2023-09-03
+keywords:
+---
+Other New Project:
+	- testing @na @butter
+Brand New Project:
+	- testing @na
+		A multi line (multiline) note
+		with a line break
+	- testing @na
+Project0:
+
+- Test1
+
+- Test2
+
+Project1:
+- Test4
+- Test5
+- Test6

data/na.gemspec

@@ -24,6 +24,7 @@ spec = Gem::Specification.new do |s|
   s.add_development_dependency('minitest', '~> 5.14')
   s.add_development_dependency('rdoc', '~> 4.3')
   s.add_runtime_dependency('chronic', '~> 0.10', '>= 0.10.2')
+  s.add_runtime_dependency('csv', '>= 3.2')
   s.add_runtime_dependency('git', '~> 3.0.0')
   s.add_runtime_dependency('gli','~> 2.21.0')
   s.add_runtime_dependency('mdless', '~> 1.0', '>= 1.0.32')

data/plugins.md

@@ -0,0 +1,38 @@
+I would like to add a plugin architecture to na_gem. It should allow the user to add plugins to ~/.local/share/na/plugins/. These plugins can be any shell script (with a shebang). They can be run with `na plugin NAME`, which accepts the plugin filename with or without an extension, and with or without spaces (so that `plugin AddFoo` will run `Add Foo.sh` if found, but the user can also use `plugin "Add Foo"`).
+
+A plugin will be a shell script that takes input on STDIN. The input should be an action as a JSON object, with the file path, line number, action text, note, and array of tags/values (`tags: [{ name: "done", value: "2025-10-29 03:00"}, { name: "na", value: ""}]`). That should be the default. 
+
+The `plugin` command should accept a `--input TYPE` flag that accepts `json`, `yaml` or `text`. The YAML should be the same as the JSON (but as YAML), and the text should just be the file_path:line_number, action text, and note, split with "||" (newlines in the note replaced with \n, and filename and line number are combined with : not the divider), with no colorization. One action per line. The "||" in `--input text` should also be a flag `--divider "STRING"` that defaults to "||", but allows the user to specify a different string to split the parts on. 
+
+The plugin will need to return output (on STDOUT) in the same format as the input (yaml, json, or text with specified divider), unless `--output FORMAT` is specified with a different type. The `plugin` command will execute the script for every command passed to it, and update the actions based on the returned output.
+
+The `plugin` command should accept all the same filter flags as `finish` or other actions that update commands. 
+
+For the `update` command, it should accept a `--plugin NAME` flag, and if it's using interactive menus, a list of plugin names (basename minus extension) should be added to the list of available operations.
+
+Also add a `--plugin NAME`, `--input TYPE`, and `--output TYPE` flag to all search and display commands (next, grep, tagged, etc.). That way the user can filter output with any command and run the result through the plugin.
+
+In lieu of the `--input` and `--output` commands, the plugin itself can have a comment block after the shebang with `key: value` pairs. When reading a plugin, check for a comment block with `input: JSON` `output: YAML` (case insensitive). The user can also define a `name` or `title` (interchangeable) in this block, which will be used instead of the base name if provided. We need to ignore leading characters when scanning for this comment block (e.g. # or //). The block can have blank lines before it. The only keys we read are input, output, and name/title. Parsing stops at the first blank line or after all three keys are populated. Other keys might exist, like `author` or `description`, which should be ignored.
+
+The plugins shouldn't need to be executable, the hashbang should be read and used to execute the script.
+
+When `na` runs, it should check for the existence of the `plugins` directory, creating it if it's missing, and adding a `~/.local/share/na/plugsin/README.md` file with plugin instructions if one doesn't exist. Any `.md` or `.bak` file in the plugins directory should be ignored. In fact, let's have a helper validate the files in the directory by checking for a shebang and ignoring if none exists, and also ignoring any '.bak' or '.md' files.
+
+Have NA also create 2 sample plugins in the `~/.local/share/na/plugins` folder when creating it (do not create plugins if the folder already exists). Have the sample plugins be a Python script and a Bash script. The sample plugins should just do something benign like add a tag with a dynamic value to the passed actions. In the README.md note that the user can delete the sample plugins. Give the sample plugins names "Add Foo.py" and "Add Bar.sh" and have them add @foo and @bar, respectively.
+
+### Summary ###
+
+- plugins are script files in ~/.local/share/na/plugins
+	- plugins require a shebang, which is used to execute them
+	- plugin base names (without extension) becomes the command name (spaces are handled)
+	- Ignore 
+- `plugin` subcommand
+	- accepts plugin name as argument
+	- has a `--input TYPE` flag that determines the input type (yaml, json, or text)
+	- has a `--output TYPE` (yaml, json, or text)
+	- has a `--divider` flag that determines the divider when `--input text` is used
+- `update` subcommand
+	- accepts a `--plugin NAME` flag
+	- Adds plugin names to interactive menu when no action is specified
+- main script parses the output of the plugin, stripping whitespace and reading it as YAML, JSON, or text split on the divider (based on `--output` and defaulting to the value of `--input`), then updates each action in the result. Line numbers should be passed on both input and output and used to update the specific actions.
+- Generate README and scripts

data/src/_README.md

@@ -9,7 +9,7 @@
 _If you're one of the rare people like me who find this useful, feel free to
 [buy me some coffee][donate]._
 
-The current version of `na` is <!--VER-->1.2.86<!--END VER-->.
+The current version of `na` is <!--VER-->1.2.87<!--END VER-->.
 
 `na` ("next action") is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for `@na` tags (or whatever you specify) in todo files in your current folder.
 
@@ -375,6 +375,115 @@ If you're using a single global file, you'll need `--cwd_as` to be `tag` or `pro
 
 After installing a hook, you'll need to close your terminal and start a new session to initialize the new commands.
 
+### Plugins
+
+NA supports a plugin system that allows you to run external scripts to transform or process actions. Plugins are stored in `~/.local/share/na/plugins` and can be written in any language with a shebang.
+
+#### Getting Started
+
+The first time NA runs, it will create the plugins directory with a README and two sample plugins:
+- `Add Foo.py` - Adds a `@foo` tag with a timestamp
+- `Add Bar.sh` - Adds a `@bar` tag
+
+You can delete or modify these sample plugins as needed.
+
+#### Running Plugins
+
+Run a plugin with:
+```bash
+na plugin PLUGIN_NAME
+```
+
+Or use plugins through the `update` command's interactive menu, or pipe actions through plugins on display commands:
+
+```bash
+na update --plugin PLUGIN_NAME           # Run plugin on selected actions
+na next --plugin PLUGIN_NAME             # Transform output only (no file writes)
+na tagged bug --plugin PLUGIN_NAME       # Filter and transform
+na find "search term" --plugin PLUGIN_NAME
+```
+
+#### Plugin Metadata
+
+Plugins can specify their behavior in a metadata block after the shebang:
+
+```bash
+#!/usr/bin/env python3
+# name: My Plugin
+# input: json
+# output: json
+```
+
+Available metadata keys (case-insensitive):
+- `input`: Input format (`json`, `yaml`, `csv`, `text`)
+- `output`: Output format
+- `name` or `title`: Display name (defaults to filename)
+
+#### Input/Output Formats
+
+Plugins accept and return action data. Use `--input` and `--output` flags to override metadata:
+
+```bash
+na plugin MY_PLUGIN --input text --output json --divider "||"
+```
+
+**JSON/YAML Schema:**
+```json
+[
+  {
+    "file_path": "todo.taskpaper",
+    "line": 15,
+    "parents": ["Project", "Subproject"],
+    "text": "- Action text @tag(value)",
+    "note": "Note content",
+    "tags": [
+      { "name": "tag", "value": "value" }
+    ]
+  }
+]
+```
+
+**Text Format:**
+```
+ACTION||ARGS||file_path:line||parents||text||note||tags
+```
+
+Default divider is `||` (configurable with `--divider`).
+- `parents`: `Parent>Child>Leaf`
+- `tags`: `name(value);name;other(value)`
+
+If the first token isn’t a known action, it’s treated as `file_path:line` and the action defaults to UPDATE.
+
+#### Actions
+
+Plugins may return an optional ACTION with arguments. Supported (case-insensitive):
+- UPDATE (default; replace text/note/tags/parents)
+- DELETE
+- COMPLETE/FINISH
+- RESTORE/UNFINISH
+- ARCHIVE
+- ADD_TAG (args: one or more tags)
+- DELETE_TAG/REMOVE_TAG (args: one or more tags)
+- MOVE (args: target project path)
+
+#### Plugin Behavior
+
+**On `update` or `plugin` command:**
+- Plugins can modify text, notes, tags, and parents
+- Changing `parents` will move the action to the new project location
+- `file_path` and `line` cannot be changed
+
+**On display commands (`next`, `tagged`, `find`):**
+- Plugins only transform STDOUT (no file writes)
+- Use returned text/note/tags/parents for rendering
+- Parent changes affect display but not file structure
+
+#### Override Formats
+
+You can override plugin defaults with flags on any command that supports `--plugin`:
+```bash
+na next --plugin FOO --input csv --output text
+```
 
 [fzf]: https://github.com/junegunn/fzf
 [gum]: https://github.com/charmbracelet/gum