mecatl Learning Config

mecatl learning configuration

Safely design and merge the operator-tier learning: policy after identifying where mecatl actually runs. Do not assume that the client and server share a host or configuration.

Progressive reference use

After deployment and target resolution (Workflow Step 1), read only the needed parts of the configuration reference:

• Exact schema and defaults always;
• Budget profiles only after the budget choice;
• Operator and project tiers only when project configuration is discussed; and
• Common errors only when validating or troubleshooting.

Do not require reading the entire reference at activation. Repository background is in user-docs/reference/configuration.md, user-docs/building/deployment/settings.md, and user-docs/features/learning.md; cite those paths as prose, not links.

Safety contract

• Resolve the deployment, startup configuration, precedence, and effective target before using Read on any settings file. Read only startup artifacts the operator identifies or that are already available in the task context; never scan processes/services or unrelated files to discover them.
• Read-only inspection and validator preflight are allowed before confirmation. The proposed preflight may write only the generated, non-secret learning: patch under the repository-local .scratch/; it is not a settings write and must be removed after validation on success, failure, or cancellation. Any settings-file creation or modification requires explicit confirmation.
• Inspect an established relevant target with the Read tool, never cat. Read the complete file. A missing file is fine. Do not print, log, or rewrite unrelated values, comments, credentials, or secret-shaped content.
• Treat malformed or unvalidated YAML as a stop condition. Do not edit until a minimal repair is understood and explicitly approved.
• Modify only the top-level learning: mapping. Preserve every other byte when targeted replacement permits it. Never rewrite the whole file merely to make YAML easier to generate.
• Before any write, show the complete proposed learning: block and exact replacement diff, then ask for explicit confirmation. Silence is not consent.
• If the file is missing, offer manual content or creation of the resolved, owner-intended path. Create it only after explicit confirmation. Never add credentials.
• The validator is read-only, uses no credentials or network, and must never print file contents.

Workflow

1. Establish deployment, startup configuration, and effective owner

Do this before choosing or reading a settings path. First classify the deployment as local standalone, local embedded mecatui, remote client/server, or engine embedder. Establish the actual startup source already supplied by the operator or task: service command, container args/config, systemd unit/overrides, or embedder code. From that source record, in order:

1. every repeatable --permission-config PATH explicit operator file;
2. whether --permissions-conventional is enabled; and
3. the server process's XDG_CONFIG_HOME, or its HOME fallback when relevant.

Do not infer these from defaults when the effective invocation may override them. If the startup command/unit/container args are not observable from authorized, relevant context, ask the operator for them. Never scan running processes, services, containers, or unrelated files.

Resolve the owning operator learning block using mecatl's actual precedence:

• inspect explicit files in CLI order, stopping at the first readable, valid file with a non-null top-level learning: block; unreadable or invalid explicit files are skipped by mecatl and cannot own the effective block;
• only when conventional discovery is enabled and no explicit file captured a learning block, consider the user file at $XDG_CONFIG_HOME/mecatl/settings.yaml, falling back to $HOME/.config/mecatl/settings.yaml when XDG_CONFIG_HOME is unset or empty; its readable, valid learning: block is then the owner; and
• files after the owner, and a conventional user file shadowed by an explicit owner, have no effect on operator learning. Never edit one of them.

Apply that resolution by deployment:

• Local standalone or embedded mecatui: resolve against the local server's actual invocation and environment, not merely the interactive shell's.
• Remote mecatui/connect: resolve only from server startup args and the server host's environment/files. Never inspect or edit local client settings. Without authorized server access, provide the exact block and server-side instructions.
• Engine embedder: configuration is code-owned unless the embedding application explicitly constructs permconfig from files. Ask the owner how it is supplied; do not invent a mecated path.

If no current block owns learning, the insertion target is the first operator-intended explicit file chosen by the operator, or the conventional user file only when conventional discovery is enabled. If ownership or an effective insertion target cannot be established, do not edit automatically: provide a manual block plus instructions to install and validate it on the owning server or in embedder code. Record the established path privately as <resolved-path>.

2. Inspect and validate the current document

Read the complete target and classify it as missing, valid without learning:, valid with learning:, or malformed. Retain the existing mapping, comments, indentation, and byte range for a later targeted edit. Report only learning-related findings.

On the server host, validate the target without exposing its content. Pass the resolved path as one quoted argument; never concatenate it into shell syntax, a command string, or another argument:

mecated config validate --file "<resolved-path>"

The command reads at most 256 KiB and prints only valid or a sanitized error. It requires the file to exist unless a learning patch is supplied. If mecated is unavailable on a remote host, do not auto-edit: give the exact block and server-side installation guidance, including actual-file validation after the operator makes the change.

3. Elicit one answer at a time

Ask in this order. Wait after every question. Each prompt must show all prior answers and the recommended default:

✓ Autonomy: <answer>
✓ Sensitivity: <answer>

→ <one current question>
  ▸ <recommended choice> (recommended — <brief reason>)
    <other choices>

1. Desired autonomy: Review first / Auto / Off. Recommend Review first for rollout. If the operator explicitly asks for autonomous learning, recommend Auto instead. Off disables observation, not explicit tools.
2. Sensitivity: conservative / balanced / eager. Recommend balanced. This is independent of budget posture: any sensitivity may be combined with any budget profile.
3. Skill activation assurance: ask this when mode is Auto. Recommend validated for usable, body-only, evidence-backed autonomy. Offer evaluated only when a trusted fixture evaluator is configured; it requires PASS. For Review/Off, record future policy or accept validated as an inert default without implying activation.
4. Budget posture: default / budget-conscious / eager / custom. Profiles set only the six automatic budget values; they never choose sensitivity. Explain that limits and cooldowns are process-local, so N replicas may reserve about N times the aggregate. They are not provider quotas or cluster-global limits. For custom, ask one automatic value at a time and validate it; do not ask for sensitivity again.
5. Existing subtree: when present, preserve or revise it. Recommend preserve and revise only selected fields. When absent, state that a new subtree will be inserted.

Support back to revise the preceding answer. Do not collapse these into one questionnaire.

4. Explain the selected behavior

Before proposing YAML, summarize mode × activation accurately:

• Off: no automatic observation/reflection. Explicit /reflect, memory and user-model tools, and SkillDraft remain available. Direct SkillDraft creates inactive content. Dream consolidation is independently configured.
• Review: admitted completions spend reflection capacity and stage durable proposals; they do not promote memory or activate learned skills.
• Auto: facts retain evidence, ownership, and conflict gates. With validated, a structurally safe, body-only, evidence-backed exact candidate activates on PASS or ABSTAIN/no evaluator. With evaluated, only trusted evaluator PASS activates. FAIL and evaluator ERROR never activate.

State separately that sensitivity selects automatic admission thresholds while budgets bound automatic frequency and reserved tokens; users may combine any sensitivity with any budget posture. Explicit /reflect bypasses automatic sensitivity, cooldown, and count/token budgets, but retains coordinator, provider, timeout, ownership, and lifecycle limits.