foliole: Instructions file for Codex

AGENTS

Read any same-directory AGENTS.local.md alongside this file; it contains private, untracked local rules. Apply the same rule in subdirectories.

Decision Order

• The user's latest instructions define the outcome. An approved plan only supplements stable goals already authorized by the user; it cannot expand authorization. Code, tests, fixtures, and controllers must not redefine the goal around the current implementation. If observed evidence disproves the formal contract, stop and refer it to the user.
• Protect user data, security, source-of-truth code, and truthful results first, then choose a route using verified current conditions. Conditional protections override implementation preferences only when their triggers are evidenced. Within these constraints, choose the fastest, shortest, mature, reproducible route.
• Root rules define hard repository-wide boundaries and mechanical entry points; directory rules refine them and apply according to the current task and observed conditions. Plans define intended semantics, not current facts.
• Preserve conditional wording. Do not enforce a protection as a permanent prohibition when its trigger is absent or its invalidation condition is met. Plans, handoffs, and execution must not turn “when” or “only under” into unconditional “must” or “must not.” A shorter, equally reliable mature route may replace an implementation preference.

Repository And Work Unit

• This is an Electron + React + TypeScript + Vite + Capacitor multiplatform monorepo. electron/, android/, and ios/ contain thin hosts; src/app/ and src/companion/ contain renderer shells; cross-host business logic, state, and stable interfaces belong in src/features/, src/store/, and src/shared/.
• Deliver one runnable, verifiable, reversible capability increment at a time. Divide increments by user outcome, data semantics, or migration semantics, not by files, tests, platforms, commit count, or elapsed time. Exclude unrelated refactoring.
• Product tasks do not implicitly authorize control-plane work. The control plane includes validators, controllers, orchestrators, gates, monitors, protocols, scanners, and general workflows that manage development, verification, acceptance, or agent execution; it excludes input validation, business controllers, and bridges required by the product. Additions or extensions require an explicit current user request or an approved plan naming them as independent deliverables with benefits and acceptance criteria. Generic requests to improve verification or complete an increment do not authorize them.
• Product increments may run existing entry points, add minimal behavior tests and necessary fixtures, and repair tool regressions introduced in the current work to restore the existing contract; repairs must not expand tool responsibilities. If removing a proposed control mechanism leaves product goals and data/security invariants intact, describe its benefit independently rather than treating it as necessary implementation. Each change must directly serve the user outcome, necessary implementation, or minimal behavior verification; no separate attribution ledger is needed. Record unauthorized control-plane gaps as separate follow-ups, continue unblocked product work, and report pending acceptance with the concrete gap when blocked. Do not build unauthorized controls or claim a pass.
• Use a shared core with thin host adapters. Put platform differences in src/shared/platform/** or the relevant host; do not duplicate platform branches in feature/store/editor business logic. Production icons, menus, and commands must share their source and names.