*louiselm.txt*  LouiseLM human reference


==============================================================================
Contents                                                   *louiselm-contents*

  1. Overview ..................................................... |louiselm|
  2. Usage history .......................................... |louiselm-usage|
  3. Sessions ............................................ |louiselm-sessions|
  4. Workflow ............................................ |louiselm-workflow|
  5. Permissions ...................................... |louiselm-permissions|
  6. Context and skills ................................... |louiselm-context|
  7. Default mappings .................................... |louiselm-mappings|
  8. Commands ............................................ |louiselm-commands|
  9. Configuration .................................. |louiselm-configuration|
  10. Optional capabilities ................. |louiselm-optional-capabilities|
  11. Session API ............................................. |louiselm-api|
  12. Troubleshooting ............................. |louiselm-troubleshooting|

==============================================================================
Overview                                                            *louiselm*

  LouiseLM is an ACP-first Neovim client with an interactive chat and a
  headless Session API.

  Sessions remain bound to their Agent. A Handoff creates a new Session with a
  configured Agent, including the current Agent, and seeds it with your
  takeover task and a compacted source transcript. The source Session remains
  attached.

Setup ~                                                     *louiselm.setup()*

  Call setup() once with at least one Agent. Every Agent needs a command and
  the Provider supplying its access or quota; see |louiselm-configuration| for
  the complete schema.

>lua
  require("louiselm").setup({
    agents = {
      claude = {
        command = "claude-code-acp",
        provider = "Anthropic",
      },
      codex = {
        command = "codex-acp",
        provider = "OpenAI",
      },
    },
    context = {
      instructions_file = "AGENTS.md",
    },
  })
<

  Then use |:LouiselmChat| to start a Session, or |louiselm-api| to drive an
  Agent without the chat UI. Use |:checkhealth| louiselm to discover optional
  capabilities and validate the prerequisites of explicitly enabled
  integrations. Ordinary chat requires an authenticated Agent and sqlite3 >=
  3.38 with JSON support.

==============================================================================
Usage history                                                 *louiselm-usage*

  |:LouiselmUsage| explores recorded usage without a live Session. Press f for
  joint filters (JSON object), g for grouping (JSON array), t for an
  inclusive/exclusive UTC range, and b to cycle UTC hour/day buckets.
  Dimensions are agent, provider, model, session and option:<recorded ID>; d
  browses recorded values and Enter applies one. Boolean false and string
  false remain distinct; JSON null matches an absent value.

  Enter drills from a summary into turns, then recorded observations and
  option transitions. Backspace returns; s shows a turn's Session timeline,
  including between-turn changes. v cycles summary/turns/events, m cycles
  mixed-turn inclusion, n/p page, r refreshes and q closes. Turn ranges use
  recorded start timestamps; event ranges use observation timestamps. Pages
  contain at most 25 rows and query committed facts asynchronously.

  Overall totals include mixed turns. Provider/Model/option summaries exclude
  changed-during-turn records and report the count; inspect those turns in the
  turn view. Each token field and currency displays its own reported total,
  mean and coverage. Missing data stays absent, currencies are never combined,
  and no prices are estimated. See docs/turn-recording.md for the headless
  store:usage_query API and exact attribution rules.

==============================================================================
Sessions                                                   *louiselm-sessions*

  A Session is bound to one Agent for its lifetime. Use |:LouiselmSessionNew|
  to start another Session without stopping the current one, and
  |:LouiselmSessionSwitch| to focus an attached Session.

  Hover the Agent name (for example, codex) in a chat window's winbar to
  display its full Agent-scoped Session ID without changing keyboard focus.
  The tooltip identifies the hovered window's Session and disappears when the
  pointer leaves the name or you type. Use |:LouiselmSessionId| to copy the
  focused Session's ID.

  Hover requires a terminal/GUI that reports mouse movement and enabled
  'mouse'. Opening the interactive chat enables 'mousemoveevent'; disposing or
  reconfiguring the UI restores its previous value unless you changed it
  afterward. Set 'nomousemoveevent' to disable hover. No mouse mappings are
  replaced. Headless Session APIs do not change these options.

  Prompt silence has no time limit. A quiet or reconnecting Agent keeps its
  Session active until it responds, reports an error, or you dispose it. Use
  |:LouiselmCancel| to request cancellation; dispose the Session if the Agent
  cannot respond. LouiseLM never resubmits an interrupted prompt
  automatically.

  Agents supporting the Session activity extension can run again after a
  prompt completes, for example when Claude wakes for a scheduled check.
  LouiseLM shows Model responding and queues input until the Agent reports
  idle. Each client prompt still completes once. Cancellation requests a stop;
  the Session remains active until the Agent acknowledges it. Agents without
  this extension retain their ordinary prompt lifecycle.

  A Handoff creates a new Session with a configured Agent after you fill in
  its takeover task and review the context. When available, it uses the latest
  usable completed ACP compaction summary plus recent conversation, including
  conservative overlap for the current instruction and open tools. Otherwise
  it uses the filtered full transcript. This is lossy context, not the Agent's
  complete replacement history. No new source turn is requested; the source
  Session and full transcript remain intact.

  Experimental ACP compaction updates appear as separate timeline rows. Use
  |:LouiselmInspectTool| on a compaction row to inspect its retained summary
  and status. Agents may omit summaries. LouiseLM consumes the shared protocol
  without adapter-specific hooks or transcript parsing; compaction does not
  replace usage telemetry or erase the source transcript.

  Cold Park requires an Agent that supports session/load and persisted
  conversation history. A fresh Session must send a prompt first; a
  successfully loaded, ready Session can Park immediately without another
  prompt. Cold resume restores recoverable history after editor exit, but
  staged context is lost.

==============================================================================
Workflow                                                   *louiselm-workflow*

  Configure an Agent, start or resume a Session, queue optional context, then
  submit a prompt. Respond deliberately to permission requests and cancel a
  current turn when the intent changes.

  Session buffers always install these buffer-local Normal-mode motions,
  independently of the global keymaps option:

  ]u / [u    Next / previous submitted prompt
  ]r / [r    Next / previous assistant reply
  ]e / [e    Next / previous [usage] row
  ]E / [E    Next / previous Error: or Warning: row
  ]x / [x    Next / previous tool run or thinking header
  <CR>       Return to the editable prompt in Insert mode

  Motions accept counts (for example 2]e), land at the first non-blank column,
  preserve folds and stay in Normal mode. If the requested target does not
  exist, the cursor stays put silently; motions never wrap. Usage and
  diagnostic targets exclude submitted prompts, context and thinking content.
  Activity motions visit the first row of each contiguous tool run, including
  single-line tools, and thinking headers even while reasoning is streaming.
  Use za to toggle a completed fold.

==============================================================================
Permissions                                             *louiselm-permissions*

  Sessions ask a human to answer ACP permission requests by default.
  Persistent choices remain scoped to the configured Agent, exact adapter
  command and arguments, and Session workspace.

  Use |:LouiselmPermissions| to inspect and revoke remembered decisions.

==============================================================================
Context and skills                                          *louiselm-context*

  Use the context commands to queue a buffer, visual selection, file, or skill
  for the next prompt. Queued context is sent only when you submit that
  prompt.

  Submitted context is folded above the user prompt. With the inject skills
  policy, open that fold with zo to see the skill-index resource type and URI.
  Its catalog body stays in a separate [body: skill-index] fold; use zo there
  to inspect it and zc to close it.

  To remove a staged skill, erase its [context: skill: NAME] chip from the
  prompt. Before submitting or staging another item, LouiseLM keeps only
  skills with intact leading chips. Edited chip fragments remain ordinary
  text; other queued context and the hidden skill catalog are retained.

  |louiselm-config-skills| decides where skills are discovered and who
  executes them.

==============================================================================
Default mappings                                           *louiselm-mappings*

  Installed by |louiselm.setup()| unless |louiselm-config-keymaps| is false.
  Capture, Beads, skill and Park mappings are installed only when their
  integration is enabled. Existing user mappings are preserved. Each mapping
  runs the command it links to; |mapleader| decides what <leader> expands to.

  n   <leader>lc     Louiselm chat                             |:LouiselmChat|
  n   <leader>lr     Louiselm resume session                 |:LouiselmResume|
  n   <leader>lR     Louiselm resume any session             |:LouiselmResume|
  n   <leader>lsn    Louiselm session new                |:LouiselmSessionNew|
  n   <leader>lsw    Louiselm session switch          |:LouiselmSessionSwitch|
  n   <leader>lsr    Louiselm session rename          |:LouiselmSessionRename|
  n   <leader>lsx    Louiselm session close            |:LouiselmSessionClose|
  n   <leader>lsi    Louiselm session id                  |:LouiselmSessionId|
  n   <leader>lso    Louiselm session options        |:LouiselmSessionOptions|
  n   <leader>lsO    Session Overview               |:LouiselmSessionOverview|
  n   <leader>lI     Louiselm capture inbox            |:LouiselmCaptureInbox|
  n   <leader>lm     Louiselm export markdown            |:LouiselmToMarkdown|
  n   <leader>lC     Louiselm cancel turn                    |:LouiselmCancel|
  n   <leader>lp     Louiselm permissions               |:LouiselmPermissions|
  n   <leader>lk     Louiselm pick skill                  |:LouiselmPickSkill|
  n   <leader>lf     Louiselm pick file                    |:LouiselmPickFile|
  n   <leader>lb     Louiselm mention buffer          |:LouiselmMentionBuffer|
  x   <leader>ls     Louiselm send selection          |:LouiselmSendSelection|
  n   <leader>le     Louiselm inline edit                    |:LouiselmInline|
  x   <leader>le     Louiselm inline edit                    |:LouiselmInline|
  n   <leader>lT     Louiselm inspect tool call         |:LouiselmInspectTool|
  n   <leader>lP     Louiselm inspect provenance  |:LouiselmInspectProvenance|
  n   <leader>lB     Louiselm inspect Beads issue       |:LouiselmInspectBead|
  n   <leader>lH     Louiselm hand off session              |:LouiselmHandOff|
  n   <leader>lF     Louiselm collect forensics           |:LouiselmForensics|
  n   <leader>lV     Louiselm view forensics          |:LouiselmForensicsView|
  n   <leader>lL     Louiselm inspect limits                 |:LouiselmLimits|
  n   <leader>ld     Louiselm queue diagnostics         |:LouiselmDiagnostics|
  n   <leader>lz     Louiselm resume parked run          |:LouiselmResumePark|

==============================================================================
Commands                                                   *louiselm-commands*

  Commands are registered by |louiselm.setup()|.

:LouiselmCancel                                              *:LouiselmCancel*
    Cancel the current louiselm turn
    Arguments: none

:LouiselmCapture                                            *:LouiselmCapture*
    Start or stop a durable speech capture
    Arguments: none

:LouiselmCaptureInbox                                  *:LouiselmCaptureInbox*
    Inspect durable captures and transcripts
    Arguments: none

:LouiselmCapturePair                                    *:LouiselmCapturePair*
    Create a one-time Android pairing QR
    Arguments: none

:LouiselmCaptureRetry                                  *:LouiselmCaptureRetry*
    Retry capture transcription
    Arguments: one required

:LouiselmCaptureRevoke                                *:LouiselmCaptureRevoke*
    Revoke an Android capture device
    Arguments: one required

:LouiselmCaptureSetup                                  *:LouiselmCaptureSetup*
    Verify capture service setup
    Arguments: none

:LouiselmCaptureStatus                                *:LouiselmCaptureStatus*
    Inspect capture and paired-device status
    Arguments: none

:LouiselmChat                                                  *:LouiselmChat*
    Open the louiselm chat buffer
    Arguments: none

:LouiselmDiagnostics                                    *:LouiselmDiagnostics*
    Queue the source buffer's diagnostics as louiselm context
    Arguments: none

:LouiselmForensics                                        *:LouiselmForensics*
    Collect private Forensics for the current or a named Session
    Arguments: any number

:LouiselmForensicsExport                            *:LouiselmForensicsExport*
    Export selected redacted Forensics evidence to a new file
    Arguments: one or more

:LouiselmForensicsView                                *:LouiselmForensicsView*
    View a Forensics record
    Arguments: optional

:LouiselmHandOff                                            *:LouiselmHandOff*
    Hand the current session's reviewed transcript off to another agent
    Arguments: none

:LouiselmInline                                              *:LouiselmInline*
    Replace the current selection with louiselm output
    Arguments: none

:LouiselmInspectBead                                    *:LouiselmInspectBead*
    Inspect the Beads issue under the cursor
    Arguments: none

:LouiselmInspectProvenance                        *:LouiselmInspectProvenance*
    Inspect commit or issue Provenance under the cursor
    Arguments: none

:LouiselmInspectTool                                    *:LouiselmInspectTool*
    Inspect the raw payload under the cursor
    Arguments: none

:LouiselmLimits                                              *:LouiselmLimits*
    Inspect account limits for the active or named louiselm Agent
    Arguments: optional

:LouiselmMentionBuffer                                *:LouiselmMentionBuffer*
    Queue the source buffer as louiselm context
    Arguments: none

:LouiselmPark                                                  *:LouiselmPark*
    Cold-Park the current louiselm Session
    Arguments: none

:LouiselmPermissions                                    *:LouiselmPermissions*
    Inspect and revoke remembered louiselm permissions
    Arguments: none

:LouiselmPickFile                                          *:LouiselmPickFile*
    Pick a file to queue as louiselm context
    Arguments: optional

:LouiselmPickSkill                                        *:LouiselmPickSkill*
    Pick a louiselm skill to invoke
    Arguments: none

:LouiselmPreflight                                        *:LouiselmPreflight*
    Inspect prospective artifacts without launching an Agent
    Arguments: one or more

:LouiselmProvenanceDecisions                    *:LouiselmProvenanceDecisions*
    Show the Provenance Decision index
    Arguments: none

:LouiselmResume[!]                                           *:LouiselmResume*
    Resume a prior louiselm session; use ! for all workspaces
    Arguments: none

:LouiselmResumePark                                      *:LouiselmResumePark*
    Resume a durable cold-Parked Run
    Arguments: none

:LouiselmSendSelection                                *:LouiselmSendSelection*
    Queue the visual selection as louiselm context
    Arguments: none

:LouiselmSessionClose                                  *:LouiselmSessionClose*
    Close the current louiselm session
    Arguments: none

:LouiselmSessionId                                        *:LouiselmSessionId*
    Copy the current agent-scoped ACP session id
    Arguments: none

:LouiselmSessionNew                                      *:LouiselmSessionNew*
    Create a separate louiselm session
    Arguments: none

:LouiselmSessionOptions                              *:LouiselmSessionOptions*
    Inspect session options; configure while idle
    Arguments: none

:LouiselmSessionOverview                            *:LouiselmSessionOverview*
    Open the current Session's file overview; closes when another Session
    gains focus
    Arguments: none

:LouiselmSessionRename                                *:LouiselmSessionRename*
    Rename the current louiselm session
    Arguments: none

:LouiselmSessionSwitch                                *:LouiselmSessionSwitch*
    Switch between louiselm sessions
    Arguments: none

:LouiselmToMarkdown                                      *:LouiselmToMarkdown*
    Export a louiselm session transcript to markdown; takes an optional
    session id
    Arguments: optional

:LouiselmTutor                                                *:LouiselmTutor*
    Open the LouiseLM onboarding Tutor
    Arguments: none

:LouiselmUsage                                                *:LouiselmUsage*
    Explore recorded usage: UTC ranges, joint filters, groups and turn details
    Arguments: none

==============================================================================
Configuration                                         *louiselm-configuration*

------------------------------------------------------------------------------
agents                                                *louiselm-config-agents*
    Type: string-keyed map of table
    Default: {}
    Description: Named ACP agent processes.

------------------------------------------------------------------------------
agents.<name>.args                          *louiselm-config-agents-name-args*
    Type: array of string
    Default: {}
    Description: Arguments passed after the executable.

------------------------------------------------------------------------------
agents.<name>.capabilities          *louiselm-config-agents-name-capabilities*
    Type: array of string
    Default: {}
    Description: Capability tags this agent declares support for (e.g.
    "image-generation"), matched against `needs-capability:*` beads labels by
    the agent selecting work; louiselm does not read beads or route work
    itself.

------------------------------------------------------------------------------
agents.<name>.command                    *louiselm-config-agents-name-command*
    Type: string
    Description: Executable to start.

------------------------------------------------------------------------------
agents.<name>.env                            *louiselm-config-agents-name-env*
    Type: string-keyed map of string
    Default: {}
    Description: Environment variables passed to the process.

------------------------------------------------------------------------------
agents.<name>.latest                      *louiselm-config-agents-name-latest*
    Type: table
    Default: {}
    Description: Optional command that resolves the agent's latest available
    version, e.g. `npm view <pkg> version`; omission disables the staleness
    check.

------------------------------------------------------------------------------
agents.<name>.latest.args            *louiselm-config-agents-name-latest-args*
    Type: array of string
    Default: {}
    Description: Arguments passed after the executable.

------------------------------------------------------------------------------
agents.<name>.latest.command      *louiselm-config-agents-name-latest-command*
    Type: string
    Description: Executable that prints the latest available version.

------------------------------------------------------------------------------
agents.<name>.latest.env              *louiselm-config-agents-name-latest-env*
    Type: string-keyed map of string
    Default: {}
    Description: Environment variables passed to the process.

------------------------------------------------------------------------------
agents.<name>.provider                  *louiselm-config-agents-name-provider*
    Type: one of: string, array of table, table
    Description: Required access/quota service: a fixed name, exact typed
    option routes, or { option, prefixes } mapping literal prefixes of an
    advertised string option to services. Exactly one route or prefix must
    match before each prompt; display names never determine Provider.

------------------------------------------------------------------------------
                                *louiselm-config-agents-name-provider-options*
agents.<name>.provider[].options
    Type: string-keyed map of one of: string, boolean

------------------------------------------------------------------------------
                               *louiselm-config-agents-name-provider-provider*
agents.<name>.provider[].provider
    Type: string

------------------------------------------------------------------------------
agents.<name>.provider.option    *louiselm-config-agents-name-provider-option*
    Type: string
    Description: Advertised string-valued option ID to match, not its display
    name.

------------------------------------------------------------------------------
                               *louiselm-config-agents-name-provider-prefixes*
agents.<name>.provider.prefixes
    Type: string-keyed map of string
    Description: Nonempty literal, case-sensitive prefixes mapped to
    access/quota services. No regex or longest-match precedence; multiple
    matches are ambiguous even for the same service.

------------------------------------------------------------------------------
agents.<name>.skills                      *louiselm-config-agents-name-skills*
    Type: table
    Default: {}
    Description: Agent-specific Agent Skills policy override; paths remain
    global and the effective value is fixed when a session is created.

------------------------------------------------------------------------------
agents.<name>.skills.policy        *louiselm-config-agents-name-skills-policy*
    Type: string
    Description: Override the global Agent Skills policy: native delegates to
    the adapter, inject uses LouiseLM discovery, and off disables automation;
    omission inherits the global policy.

------------------------------------------------------------------------------
                               *louiselm-config-agents-name-transcript-layout*
agents.<name>.transcript_layout
    Type: string
    Default: ""
    Description: Optional Provenance layout override for this Agent's
    historical transcripts: claude, codex, openai-compatible, or copilot; live
    chat transcripts need no configuration; omission searches all supported
    layouts.

------------------------------------------------------------------------------
agents.<name>.upgrade                    *louiselm-config-agents-name-upgrade*
    Type: one of: array of string, string
    Default: {}
    Description: Optional upgrade executable and arguments (e.g. { 'npm',
    'install', '-g', 'my-agent@latest' }), or a nonblank string explaining a
    manual update (e.g. 'Update and rebuild /path/to/checkout; global npm
    upgrades do not affect this copy.'). Displayed in outdated-Agent warnings,
    never executed. Only argv commands are shell-escaped and joined with &&
    when every outdated Agent has one; manual instructions are never included
    in that command.

------------------------------------------------------------------------------
agents.<name>.version                    *louiselm-config-agents-name-version*
    Type: table
    Default: {}
    Description: Optional override for querying the installed version,
    verbatim (nothing is auto-appended). Use when `command args... --version`
    is not the right invocation, e.g. a subcommand-based CLI wrapped by a
    debug script.

------------------------------------------------------------------------------
agents.<name>.version.args          *louiselm-config-agents-name-version-args*
    Type: array of string
    Default: {}
    Description: Arguments passed after the executable.

------------------------------------------------------------------------------
agents.<name>.version.command    *louiselm-config-agents-name-version-command*
    Type: string
    Description: Executable that prints the installed version.

------------------------------------------------------------------------------
agents.<name>.version.env            *louiselm-config-agents-name-version-env*
    Type: string-keyed map of string
    Default: {}
    Description: Environment variables passed to the process.

------------------------------------------------------------------------------
attention                                          *louiselm-config-attention*
    Type: table
    Default: {}
    Description: Durable Attention integration; local Session status remains
    available independently.

------------------------------------------------------------------------------
attention.enabled                          *louiselm-config-attention-enabled*
    Type: boolean
    Default: false
    Description: Connect to the explicitly configured local Attention service;
    does not enable capture or delivery.

------------------------------------------------------------------------------
beads                                                  *louiselm-config-beads*
    Type: table
    Default: {}
    Description: Beads issue-inspector settings.

------------------------------------------------------------------------------
beads.enabled                                  *louiselm-config-beads-enabled*
    Type: boolean
    Default: false
    Description: Enable Beads inspection of existing workspaces; never
    initialize a tracker.

------------------------------------------------------------------------------
beads.sibling_roots                      *louiselm-config-beads-sibling-roots*
    Type: array of string
    Default: {}
    Description: Directories globbed one level for a sibling
    `.beads/beads.db`, tried in order when the cursor is on a full issue ID
    belonging to a different workspace's prefix; empty disables
    cross-workspace lookup.

------------------------------------------------------------------------------
capture                                              *louiselm-config-capture*
    Type: table
    Default: {}
    Description: Durable speech-capture command settings.

------------------------------------------------------------------------------
capture.enabled                              *louiselm-config-capture-enabled*
    Type: boolean
    Default: false
    Description: Enable desktop capture commands. Receiver, transcription and
    push require separate service opt-ins.

------------------------------------------------------------------------------
capture.recorder                            *louiselm-config-capture-recorder*
    Type: array of string
    Default: {}
    Description: Recorder argv with one {output} placeholder.

------------------------------------------------------------------------------
capture.service                              *louiselm-config-capture-service*
    Type: array of string
    Default: {}
    Description: Capture-service argv prefix.

------------------------------------------------------------------------------
context                                              *louiselm-config-context*
    Type: table
    Default: {}
    Description: Project-context injection settings.

------------------------------------------------------------------------------
context.instructions_file          *louiselm-config-context-instructions-file*
    Type: string
    Default: ""
    Description: Project-root filename attached as a resource_link on new
    sessions; empty disables.

------------------------------------------------------------------------------
keymaps                                              *louiselm-config-keymaps*
    Type: boolean
    Default: true
    Description: Install LouiseLM's global default keymaps; false disables
    them.

------------------------------------------------------------------------------
skills                                                *louiselm-config-skills*
    Type: table
    Default: {}
    Description: Agent Skill discovery and injection settings.

------------------------------------------------------------------------------
skills.management                          *louiselm-config-skills-management*
    Type: table
    Default: {}
    Description: Trusted skill-management integration; independent of skill
    invocation and Admission.

------------------------------------------------------------------------------
skills.management.enabled          *louiselm-config-skills-management-enabled*
    Type: boolean
    Default: false
    Description: Expose installed trusted skill-management operations; never
    install tools or admit skills automatically.

------------------------------------------------------------------------------
skills.paths                                    *louiselm-config-skills-paths*
    Type: array of string
    Default: {}
    Description: Global directories searched for Agent Skills; relative paths
    resolve against each session workspace.

------------------------------------------------------------------------------
skills.policy                                  *louiselm-config-skills-policy*
    Type: string
    Default: "off"
    Description: Default Agent Skills policy: native delegates to the adapter,
    inject uses LouiseLM discovery, and off disables automation.

------------------------------------------------------------------------------
workflows                                          *louiselm-config-workflows*
    Type: table
    Default: {}
    Description: Workflow Run and Park integration; ordinary Handoff remains
    available independently.

------------------------------------------------------------------------------
workflows.enabled                          *louiselm-config-workflows-enabled*
    Type: boolean
    Default: false
    Description: Enable workflow Runs and Park, subject to operation-specific
    prerequisites.

==============================================================================
Optional capabilities                         *louiselm-optional-capabilities*

  Attention, Beads, desktop capture, workflow Runs and trusted skill
  management default to disabled. skills.policy defaults to off; explicit
  native/inject choices and per-Agent overrides remain available. Installed
  tools, skill paths, tracker directories and credentials never enable
  integrations. Agent permission and YOLO choices are independent.
>lua
  -- Explicit opt-ins for an operator who wants every delivered integration:
  attention = { enabled = true },
  beads = { enabled = true },
  capture = { enabled = true },
  workflows = { enabled = true },
  skills = { policy = "native", paths = {}, management = { enabled = true } },
<

  These fields belong inside setup({...}). Run |:checkhealth| louiselm for
  setup guidance and readiness. It never installs dependencies, starts
  services, initializes Beads, pairs devices, enrolls trust or admits skills.
  Disabled commands explain the required setting. Close live Sessions and
  finish recording/ingestion before reconfiguring; retained data is never
  deleted by a toggle.

  Service choices belong in ~/.config/louiselm/capture.env:
  LOUISELM_ATTENTION_ENABLED, LOUISELM_RUNS_ENABLED,
  LOUISELM_RECEIVER_ENABLED, LOUISELM_TRANSCRIPTION_ENABLED and
  LOUISELM_PUSH_ENABLED each require true. Omission means false.
  Attention-only startup needs no microphone, receiver or cloud credentials.
  Runs require LOUISELM_BEADS_WORKSPACE and LOUISELM_REAL_BR for cleanup. Cold
  Park also requires explicit editor Attention and Beads opt-ins, a ready
  service, and resumable Agent history. Keep Run support enabled while
  retained Runs have obligations.

  Manual installation and service setup are documented in
  capture-service/README.md in the plugin checkout. Desktop capture retains
  audio locally; transcription explicitly sends audio to the configured OpenAI
  API, and push uses separately configured Google credentials. The client
  cannot reconfigure a daemon shared by another editor.

  Trusted skill management currently exposes |:LouiselmPreflight| for selected
  artifacts. Packaging, Admission, and trust operations remain explicit
  installed CLI operations documented in skills-core/README.md. Enabling
  management never grants Verified posture or changes an Agent launch command.

==============================================================================
Session API                                                     *louiselm-api*

  The headless Session API drives Agents without the chat UI. It takes the
  same Agent definitions as |louiselm-config-agents|, returns the definitions
  it rejected instead of raising, and hands back Sessions the caller owns and
  disposes.

>lua
  local Session = require("louiselm.session")
  local api, errors = Session.new({
    codex = { command = "codex-acp", provider = "OpenAI" },
  })
  if not api then
    return vim.notify(vim.inspect(errors), vim.log.levels.ERROR)
  end

  api:create_session("codex", { cwd = vim.uv.cwd() }, function(session, err)
    if not session then
      return vim.notify(err, vim.log.levels.ERROR)
    end
    session:prompt("Summarise AGENTS.md", function(_, prompt_error)
      if prompt_error then
        vim.notify(prompt_error, vim.log.levels.ERROR)
      end
      session:dispose()
    end)
  end)
<

  Prompt completion, permission requests, and Agent output arrive as typed
  events on the Session. doc/api.md in the repository is the complete typed
  surface, generated from the same annotations.

==============================================================================
Troubleshooting                                     *louiselm-troubleshooting*

  Run |:checkhealth| louiselm to validate configuration and local tool
  availability. For Session-specific reports, |:LouiselmSessionId| copies the
  Agent-scoped ACP Session identifier.

  Direct vendor commands, including wrappers, have no LouiseLM Verified
  posture. With skills.management.enabled = true and louiselm-skills on PATH,
  |:LouiselmPreflight| {request-file} [{manifest-file} [{prior-request-file}
  {prior-manifest-file}]] asynchronously inspects canonical launch request/2
  and Session input-manifest/1 artifacts and opens health. Prior files are
  explicitly selected, never inferred from history.

  The selected prospective snapshot separates proposed identities from
  independently checked supply/runtime artifacts. Native loading, isolation,
  network enforcement and disclosure remain unproven; network scope is
  unresolved without revision-bound rules. The snapshot is not approval,
  launch authority or live Session status. Refresh after input changes; future
  launch integration must bind the exact displayed request digest. Setup/reset
  forgets the selection and cancels pending reads.

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