diff --git a/AGENTS.md b/AGENTS.md
index be9088d..bacc196 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,10 @@
 # Agent Notes
 
+## Documentation Maintenance
+
+Whenever adding an option to @lua/bullets/config.lua be sure to also document it
+in README.md
+
 ## OpenSpec
 
 OpenSpec specs live under `openspec/specs/<capability>/spec.md`. Keep specs split by user-facing capability instead of by Lua module or test file.
diff --git a/README.md b/README.md
index adb23f0..5d1866f 100644
--- a/README.md
+++ b/README.md
@@ -16,8 +16,11 @@ With [lazy.nvim](https://github.com/folke/lazy.nvim):
 Configure options through `opts`:
 
 ```lua
-{
+-- automatic bulleted lists
+---@type LazySpec
+return {
   "bullets-vim/bullets.nvim",
+  ---@type bullets.Config
   opts = {
     enabled_file_types = { "markdown", "text", "gitcommit" },
     mapping_leader = "",
@@ -38,7 +41,11 @@ Configure this plugin only with `require("bullets").setup({})` or lazy.nvim `opt
 
 Defaults from `lua/bullets/config.lua`:
 
+The `bullets.Config` type annotation gives LuaLS completion and diagnostics for
+available options when this plugin is in your editor's Lua workspace.
+
 ```lua
+---@type bullets.Config
 {
   enabled_file_types = { "markdown", "text", "gitcommit" },
   enable_in_empty_buffers = false,
diff --git a/lua/bullets/config.lua b/lua/bullets/config.lua
index cd2fc1f..4f39145 100644
--- a/lua/bullets/config.lua
+++ b/lua/bullets/config.lua
@@ -1,5 +1,34 @@
 local M = {}
 
+---@alias bullets.MappingMode string|string[]
+---@alias bullets.MappingRhs string|function
+
+---@class bullets.CustomMapping
+---@field [1] bullets.MappingMode
+---@field [2] string
+---@field [3] bullets.MappingRhs
+
+---@class bullets.Config
+---@field enabled_file_types? string[] Filetypes where bullets.nvim attaches.
+---@field enable_in_empty_buffers? boolean Attach to buffers with an empty filetype.
+---@field set_mappings? boolean Install default buffer-local mappings.
+---@field mapping_leader? string Prefix added before default mappings.
+---@field custom_mappings? bullets.CustomMapping[] Extra buffer-local mappings passed to `vim.keymap.set` as `{ mode, lhs, rhs }`.
+---@field delete_last_bullet_if_empty? 0|1|2 Behavior when continuing an empty bullet.
+---@field line_spacing? integer Blank lines inserted between continued bullets.
+---@field pad_right? boolean Pad ordered-list prefixes to keep text aligned.
+---@field max_alpha_characters? integer Maximum length for alphabetic list markers.
+---@field enable_roman_list? boolean Enable roman numeral list markers.
+---@field list_item_styles? string[] List marker styles recognized by the parser.
+---@field outline_levels? string[] Marker styles used when promoting or demoting bullets.
+---@field renumber_on_change? boolean Renumber affected lists after structural changes.
+---@field nested_checkboxes? boolean Recompute parent checkbox states from children.
+---@field enable_wrapped_lines? boolean Keep wrapped list text aligned.
+---@field checkbox_markers? string Characters used as checkbox states.
+---@field checkbox_partials_toggle? 0|1 How partial checkbox states toggle.
+---@field auto_indent_after_colon? boolean Indent a new child item after a bullet ending in `:`.
+
+---@type bullets.Config
 M.defaults = {
   enabled_file_types = { 'markdown', 'text', 'gitcommit' },
   enable_in_empty_buffers = false,
@@ -21,8 +50,11 @@ M.defaults = {
   auto_indent_after_colon = true,
 }
 
+---@type bullets.Config
 M.options = vim.deepcopy(M.defaults)
 
+---@param options? bullets.Config
+---@return bullets.Config
 function M.setup(options)
   M.options = vim.tbl_deep_extend('force', vim.deepcopy(M.defaults), options or {})
   return M.options
diff --git a/lua/bullets/init.lua b/lua/bullets/init.lua
index 8efc2aa..701ca21 100644
--- a/lua/bullets/init.lua
+++ b/lua/bullets/init.lua
@@ -168,6 +168,7 @@ local function add_autocmds()
   end
 end
 
+---@param options? bullets.Config
 function M.setup(options)
   M.did_setup = true
   config.setup(options)