Configuration Assistant Plugin

The Configuration Assistant gives administrators a chat that edits this Codumentor instance's own configuration in plain language — "add this repo", "switch the main model to the fast slot", "enable the redmine plugin and tell me what secret it needs", "why are webhooks failing?" — instead of hand-editing YAML against the configuration reference.

It runs against the running instance (this server). A Configuration Assistant launcher on the Admin page opens a normal chat that only admins can create. Ordinary conversations are unchanged.

The safety flow

One typical turn:

Ground — read the current config, the live schema (keys, types, defaults, and what a change costs to apply), and the matching docs section.
Propose — build a candidate change, validate it against the real loader, and show a YAML diff plus whether each changed section applies live, rebuilds a subsystem, or needs a restart. An invalid change is reported with the error and never offered for apply.
Approve — applying or rolling back asks for your confirmation on the diff before anything is written.
Apply — a timestamped backup is written next to the config file, the leaf file is updated, then hot-reload runs. The result (applied / rebuilt / restart required / errors) is shown in the chat.
Rollback — restore the most recent backup and reload.

What the assistant can do

These are the tools you will see in the chat. Read tools never ask for approval; apply and rollback do.

Tool	Approval	Purpose
`config_schema`	none (read)	Keys, types, defaults, and whether a section applies live, rebuilds, or needs a restart. Also a plugin's `args` schema — including a plugin that is documented but not installed yet.
`config_read`	none (read)	The running config (env-substituted; secret values redacted).
`plugin_config`	none (read)	Installed plugins, documented plugins not yet installed, and how to add one. Any section of a plugin's catalog page (`topic=`), or all of it.
`config_docs`	none (read)	Sections of the configuration reference on demand. Per-plugin docs are in the catalog, via `plugin_config`.
`read_logs`	none (read)	Tail / search the configured log file to diagnose problems.
`config_propose`	none (read)	Validate a patch and return the exact YAML diff. Writes nothing.
`config_apply`	you approve first	Re-validate, back up, write the leaf config, then hot-reload.
`config_rollback`	you approve first	Restore the most recent timestamped backup and reload.
`read_content`	none (read)	Page through a result that was too large to return in one piece.

The catalog it can see is the one this build contains. An executable is built
as one edition, and a plugin outside it is not "not installed yet" but absent, so
the assistant does not list it, does not offer its configuration, and says so
plainly if you ask for it by name — rather than proposing a config the plugin
loader would refuse. codumentor build-info is the same answer from the CLI.

Configuration

plugins:
  - module: codumentor.plugins.configuration_assistant
    class: ConfigurationAssistantPlugin
    args:
      enabled: true

Parameter	Type	Default	Description
`enabled`	bool	`true`	Master on/off. When false, the Admin-page launcher is hidden.

No other settings. The assistant can target two overlay files (see overlay_targets on config_schema with no section):

target=user — $CODUMENTOR_HOME/config.yaml (models, API keys, auth, personal plugins)
target=project — the discovered or --config YAML (repos, project plugins)

Omit target to edit the default leaf. A discovered project YAML still cannot set model endpoints or auth; those stay in the user overlay. The assistant does not edit deeper files in an extends: chain.

Only users with the admin:* permission can open a configuration-assistant chat.

What a change costs

Shown up front before you approve:

🟢 live — read fresh on each use; applies immediately (for example tools, ui, branding).
🟡 rebuild — a subsystem reloads to apply it (for example models, agent, prompt, plugins, logging, repos).
🔴 restart — written but not applied at runtime; needs a process restart (for example api, auth, vector_db, cache, ingestion).

Notes & limitations

Comments and formatting outside the changed keys are kept on write. Every write is still preceded by a timestamped <config>.bak.<UTC> next to the leaf file; config_rollback restores it. The proposed diff is the semantic change, not comment churn.
Secrets are not written. If a change needs a per-user / ${secret:…} secret, the assistant points you at Settings → User Secrets; it does not set secrets itself.
Edits target the leaf file, not deeper files in an extends: chain. If that leaf uses plugins_overrides, plugin changes should be proposed that way rather than replacing the whole plugins list.