*symvault.txt*	Symaira Neovim plugin

Author:  Symaira contributors <https://github.com/danieljustus/symaira-vault>
License: Apache-2.0

==============================================================================
CONTENTS                                                *symvault-contents*

  1. Introduction ................... |symvault-intro|
  2. Requirements ................... |symvault-requirements|
  3. Installation ................... |symvault-install|
  4. Configuration .................. |symvault-config|
  5. Commands ....................... |symvault-commands|
  6. Health Check ................... |symvault-health|
  7. Security ....................... |symvault-security|
  8. Lua API ........................ |symvault-api|

==============================================================================
1. INTRODUCTION                                          *symvault-intro*

Symaira for Neovim integrates Symaira secret management into your editor.
Browse, search, copy, and insert secrets without leaving Neovim.

All secret values are masked as `***` in every UI element. Secrets are never
stored in Neovim state, registers, or logs.

==============================================================================
2. REQUIREMENTS                                      *symvault-requirements*

- Symaira CLI installed and configured >
    brew install symvault
<
- Neovim >= 0.7
- plenary.nvim (https://github.com/nvim-lua/plenary.nvim)
- Symaira MCP server running >
    symvault serve --port 8080
<

==============================================================================
3. INSTALLATION                                        *symvault-install*

lazy.nvim ~
>
  {
    dir = "/path/to/symvault/editors/nvim",
    dependencies = { "nvim-lua/plenary.nvim" },
    cmd = { "SymairaList", "SymairaGet", "SymairaCopy", "SymairaGenerate", "SymairaFind", "SymairaGenerateTOTP" },
    opts = {},
  }
<

packer.nvim ~
>
  use {
    "/path/to/symvault/editors/nvim",
    requires = { "nvim-lua/plenary.nvim" },
    config = function()
      require("symvault").setup()
    end,
  }
<

Manual ~
>
  vim.opt.runtimepath:append("/path/to/symvault/editors/nvim")
  require("symvault").setup()
<

==============================================================================
4. CONFIGURATION                                        *symvault-config*

Default configuration:
>
  require("symvault").setup({
    base_url = "http://127.0.0.1:8080",
    agent_name = "nvim",
    timeout_ms = 30000,
    masking_char = "*",
    preserve_keys = { "path", "meta", "type", "name", "version", "created", "updated" },
  })
<

base_url        URL of the running Symaira MCP server.
agent_name      Agent identifier sent via X-Symaira-Agent header.
timeout_ms      HTTP request timeout in milliseconds.
masking_char    Character used for masking secret values.
preserve_keys   Table of field names whose values are never masked.

==============================================================================
5. COMMANDS                                              *symvault-commands*

:SymairaList                                           *:SymairaList*
    Open interactive vault entry picker. Selecting an entry shows its
    masked details in a floating window. Press `q` to close.

:SymairaGet [path]                                     *:SymairaGet*
    Retrieve an entry's password and insert it at cursor position. If no
    path is given, opens the vault picker.

:SymairaCopy [path]                                    *:SymairaCopy*
    Copy an entry's password to the system clipboard via the MCP
    copy_to_clipboard tool (server-side auto-clear). If no path is
    given, opens the vault picker.

:SymairaGenerate [length]                              *:SymairaGenerate*
    Generate a secure random password and insert it at cursor position.
    Default length: 24.

:SymairaFind [query]                                   *:SymairaFind*
    Search vault entries by free-text query. If no query is given,
    prompts for input.

:SymairaGenerateTOTP [path]                            *:SymairaGenerateTOTP*
    Generate a TOTP code for the specified entry and insert it at
    cursor position. If no path is given, opens the vault picker.

==============================================================================
6. HEALTH CHECK                                          *symvault-health*

Run |:checkhealth| symvault to verify:
- MCP token present at ~/.symvault/mcp-token
- plenary.nvim is installed
- Symaira CLI is available in PATH
- MCP server is reachable

==============================================================================
7. SECURITY                                            *symvault-security*

- All secret values display as `***` in the UI (symvault-masking)
- Secrets never persist in Neovim state, registers, or :messages log
- Clipboard operations use server-side copy_to_clipboard with auto-clear
- MCP bearer token is read from ~/.symvault/mcp-token at session start
- No telemetry, no cloud dependency

==============================================================================
8. LUA API                                                *symvault-api*

symvault.client.call_tool({name}, {args}, {callback})   *symvault.client.call_tool()*
    Call an MCP tool on the server. {callback} receives (err, result).

symvault.masking.mask_value({value})                *symvault.masking.mask_value()*
    Mask a single string value, returning "***".

symvault.masking.mask_object({obj})                 *symvault.masking.mask_object()*
    Recursively mask all string values in a table.

symvault.masking.mask_entry({entry})                *symvault.masking.mask_entry()*
    Mask an entry's data fields while preserving path and metadata.

symvault.picker.pick_vault_entry({opts})          *symvault.picker.pick_vault_entry()*
    Open interactive vault entry picker. {opts} can include:
    - prompt: string (picker title)
    - on_select: function(path) (called on selection)

symvault.picker.show_entry_detail({path})       *symvault.picker.show_entry_detail()*
    Show masked entry details in a floating window.

symvault.auth.read_token()                            *symvault.auth.read_token()*
    Read the MCP bearer token from ~/.symvault/mcp-token.

symvault.auth.build_headers()                       *symvault.auth.build_headers()*
    Build HTTP headers map for MCP requests.

==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl:
