docs: propose mecatui local provider setup contract

[JAORMX]

Authorized Codex amendment (2026-09-12)

• Original proposed baseline: a35157e5595edc7f26d114271959b30104ff8e4a.
• Exact amendment: e30308fae2839752350763a16a84b27316b7f2dd.
• The directing human explicitly authorized incorporating Jakub's existing manual openai-codex support into passive status and default reuse, and continuing draft implementation PR feat: add guided local provider setup #1441 before this plan merges. This is a narrow sequencing exception, not merged-plan approval.
• Public OpenAI API keys stay distinct from subscription OAuth. Existing auth-file schema and local runtime validation are reused; there is no upstream login, refresh, import, token prompt, or Codex credential mutation.
• Codex has no static default/offline entitlement inventory. Manual selectors use existing deployment-default validation, not a new entitlement policy. The previous claim that native Codex login exists was corrected.
• Amended AC1.1/AC2.3/AC2.4 retain four scenarios and 15 criteria. Checker, checker regressions, and task docs passed; post-push plan CI is green (non-applicable code jobs skipped).

Summary

• Propose the first local mecatui llm setup and passive aggregate-status contract.
• Define existing credential custody, four-state ordered commit semantics, and filesystem/security boundaries in proposed ADR 0332.
• Record the four implementation scenarios and exact verification proofs without implementation code.

Development stage

• Plan / Interface — Bounded/Architectural behavioral and exact-interface contract; no implementation
• Implementation — based on an approved, merged Plan / Interface PR
• Combined — compact one-task Bounded/Architectural exception
• Spike / Routine — acceptance-plan spine exempt

Contract linkage

• Work classification: Architectural
• Classification rationale: Guided credential persistence establishes durable operator-custody, partial-commit, and security contracts across the CLI, auth.yaml, and provider defaults.
• Decision record: Proposed ADR 0332
• Human waiver of spine: No
• Acceptance plan: Mecatui local provider setup
• Human decisions resolved and recorded: Yes
• Plan / Interface PR: This PR
• Approved commit baseline: Not yet approved; merge of this PR is the approval event.
• Combined/exemption rationale: N/A — Split delivery.

Interface conformance

The proposed contract adds root-internal outcome-typed API-key and settings writers, mecatui llm setup [--auth-file PATH], and passive no-target mecatui llm status. It preserves startup credential precedence and native/ToolHive custody, introduces no gRPC/protobuf, engine API, provider-module, or model-facing tool changes, and explicitly reports partial commit durability.

Issue relationship

No issue reference supplied.

Type of change

• Behavioral/interface plan
• Bug fix
• New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation/process
• Other (describe):

Test plan

Baseline checks

• Acceptance-plan checker
• Linting (task lint) — implementation gate, not applicable to this documentation-only plan
• Offline test suite (task test) — implementation gate, not applicable to this documentation-only plan
• Offline demo (go run ./cmd/mecademo) — implementation gate, not applicable to this documentation-only plan
• Markdown changed: docs generation/link checks (task docs)
• User docs/user-facing behavior changed: site build (task site:build) — no behavior is implemented in this PR
• Guarded engine API affected: compatibility check (task api:check) — no engine API change
• Intentional engine API change: task api:update + engine/CHANGELOG.md — no engine API change
• Landed plan: strict acceptance trace (task ac-trace-strict) — plan remains proposed
• Final implementation review: /panel-review — implementation gate

Checker regression fixtures and git diff --check also passed. Full task docs used the repository-pinned pnpm 11.25.0 from ignored repo-local tooling and produced no lockfile or generated-document drift.

Changes

File	Change
docs/acceptance/mecatui-local-provider-setup.md	Proposed exact behavior, interfaces, acceptance criteria, and risks
docs/adr/0332-mecatui-local-provider-enrollment.md	Proposed custody, persistence, and passive-status decision
Acceptance/ADR indexes	Link the proposed contract documents

User-facing change

None — this PR defines a proposed contract and contains no source implementation.

Special notes for reviewers

Please scrutinize the four-state commit/error contract, credential-parent ownership boundary, comparison-to-rename residual, separate confirmation ordering, and truthful post-rename durability reporting. The ADR and acceptance plan remain proposed until this PR is merged.