lobu: Instructions file for Codex

Repo map

• Bun workspace under packages/*; TS source in src, tests in __tests__.
• core types/utils · plugin-api plugin contracts · plugin-host plugin composition · server gateway + embedded runtime · connector-worker connector jobs and agent turns (V8 isolates) · connectors built-in connectors · owletto frontend submodule.
• Read the nearest package AGENTS.md before editing that package; grep docs/GOTCHAS.md when something looks inexplicable.

Unrecoverable — never do these

• Never write to ~/Code/lobu directly. Run make task-setup NAME=<slug> first, and never git switch in the main checkout — other sessions share it. For a pure submodule-pointer bump, make bump SUBMODULE=packages/owletto is the lightweight isolated-worktree exception; it also posts the required statuses.
• Stage by explicit path (git add -- <paths>, never -A). A commit is a snapshot, so a stale file copy left by earlier work in the same worktree silently reverts merged PRs. After commit/rebase, git diff --name-only origin/main...HEAD must equal your intended file list; extras = stop.
• events is append-only. Never DELETE FROM events; tombstone or supersede instead.
• Never bulk-delete prod organization rows, including zero-activity ones — empty-looking orgs are usually real signups. Surface them one at a time for confirmation.
• Never resolve merge conflicts in the GitHub web UI — it has silently dropped 1000+ lines of feature work. Rebase locally against origin/main; submodule-pointer branches git merge instead (docs/GOTCHAS.md).
• Two writing agents must never share a worktree — they overwrite each other's uncommitted work. Every subagent with Edit/Write/Bash gets its own through make task-setup (only task-setup does submodule pinning, bun install, .env copy, and port allocation); only read-only agents share the parent.
• Never add a table or change DB design, API surface, or SDK surface without surfacing the proposal and receiving confirmation first.
• Never auto-submit an interactive browser draft, in any package. Drafts are page-activated: persist the operation, notify normally, and let the extension activate the run only when the user visits a pending URL in a user-owned tab. Only scrape-owned scratch tabs may be opened and closed automatically. Server, connector, and Owletto code all obey this (packages/server/AGENTS.md).
• Tenant/example state stays with its owner. Entity/relationship schemas, event kinds, Automations, prompts, agents, device pins, task IDs, and policies for one org, customer, project, or example belong in that example/config — never shared core, server, worker, SDK, or migrations. Before editing shared packages for an example, state the reusable platform invariant; if there is none, stop. Design-lock a genuinely missing public API/DB/cross-runtime contract as a separate PR.
• Shared runtime never special-cases user entity keys. Only reserved $... entity types are platform-owned. All other semantics come from the entity schema or an explicit generic contract; an existing literal such as person or company is not precedent.
• Connector logic stays connector-owned. Put it in the connector implementation or an explicitly named connector adapter/auth/webhook/migration module, registered through a generic contract. Never add connector-slug branches to otherwise generic runtime modules; extend the connector contract when the generic path lacks a capability.
• Never commit live tenant identifiers or personal machine state. No real org UUIDs, entity/Automation/device/connection IDs, usernames, personal absolute paths, or task numbers in shipping code, shared migrations, or script defaults. Tenant state belongs in its example/config; tests use clearly synthetic values; operational scripts require explicit inputs.
• Generated and published artifacts must be portable. Never embed a developer's home, checkout, or worktree directory in catalogs, bundles, metadata, lockfiles, or package contents. Resolve runtime paths from installed assets or explicit user configuration; use synthetic paths in fixtures. Enforce this on generated/packed bytes with portability tests, including foreign build-machine paths and encoded file URLs — source grep alone cannot detect build-time leaks.